Python calendar — Month, Weekday, and Leap Year
Many programs need calendar facts that are awkward to count by hand: what weekday a date falls on, how many days a month has, whether a year is a leap year, and how the days of a month line up in weeks. The calendar module answers all of those with no package to install, and it prints a plain-text month when a reader or a log needs one. This guide takes those parts in turn, then the Calendar class, text output, and the setting that moves the first day of the week. Date and time arithmetic itself belongs to the datetime module, which this guide links to instead of repeating.
Written November 17, 2026 · Tested with Python 3.12.3 · 11 min read
- Finding a weekday: weekday
- Leap years: isleap and leapdays
- A month's first weekday and length: monthrange
- A month as week rows: monthcalendar
Written November 17, 2026
Tested with Python 3.12.3
What this guide is
The calendar module works with whole days, months, and years. It reports weekdays, month lengths, and leap years, arranges a month into weeks, and formats a month as text or HTML. It does not carry times, time zones, or durations: a value here is a year, a month number from 1 to 12, and a day number. Programs that need a date as an object, or the difference between two dates, use the datetime module for that work and use calendar for the month-shaped questions around it.
Finding a weekday: weekday
calendar.weekday(year, month, day) returns the weekday of a date as a number, with Monday as 0 and Sunday as 6. That numbering matches the module constants calendar.MONDAY through calendar.SUNDAY, and it indexes directly into calendar.day_name, so a number a program computes can become a name a reader sees:
import calendar
for date in ((2026, 11, 17), (2026, 11, 1), (2024, 2, 29), (2000, 1, 1)):
day = calendar.weekday(*date)
print(date, int(day), calendar.day_name[day])
print(calendar.MONDAY, calendar.SUNDAY)
The exact output:
(2026, 11, 17) 1 Tuesday
(2026, 11, 1) 6 Sunday
(2024, 2, 29) 3 Thursday
(2000, 1, 1) 5 Saturday
0 6
November 17, 2026 is a Tuesday, and the result 1 says so in the module's numbering. The last line fixes the ends of the range in memory: Monday is 0, not 1, and Sunday is 6, not 7. Code that assumes Sunday is 0, as some other languages number it, will be off by one for every date it touches, so the constant names are the safer way to write a comparison when the weekday matters by name.
Leap years: isleap and leapdays
A year is a leap year when it divides by 4, except that a year dividing by 100 is not a leap year unless it also divides by 400. calendar.isleap(year) applies that whole rule and returns True or False, and calendar.leapdays(y1, y2) counts the leap days in the years from y1 up to but not including y2:
import calendar
for year in (2000, 1900, 2024, 2026):
print(year, calendar.isleap(year))
print("2000 to 2024:", calendar.leapdays(2000, 2025))
print("2020 to 2029:", calendar.leapdays(2020, 2030))
print("1900 to 2000:", calendar.leapdays(1900, 2001))
The exact output:
2000 True
1900 False
2024 True
2026 False
2000 to 2024: 7
2020 to 2029: 3
1900 to 2000: 25
The first two lines are the pair that catches a divide-by-4 shortcut: 2000 is a leap year because it divides by 400, and 1900 is not, even though it divides by 4 and by 100. The count for 1900 to 2000 carries the same lesson in aggregate: the leap years in that span run from 1904 to 2000 in steps of four, giving 25, because 1900 contributes nothing and 2000, at the end of the span, does. A hand-rolled rule that only tests division by 4 gets both century cases wrong.
A month's first weekday and length: monthrange
calendar.monthrange(year, month) returns a pair: the weekday of the first day of the month, in the same Monday-as-0 numbering as weekday, and the number of days in the month. February is where the second value earns its keep, because it changes with the leap-year rule:
import calendar
for year, month in ((2026, 11), (2024, 2), (2026, 2), (2027, 2)):
first, days = calendar.monthrange(year, month)
print(year, month, int(first), calendar.day_name[first], days)
The exact output:
2026 11 6 Sunday 30
2024 2 3 Thursday 29
2026 2 6 Sunday 28
2027 2 0 Monday 28
November 2026 starts on a Sunday and has 30 days. February has 29 days in the leap year 2024 and 28 in both 2026 and 2027, with no special case in the calling code. A program that builds a month view, validates a day number a user typed, or finds the last day of a month can read the length from here instead of keeping its own table of month lengths plus a February exception.
A month as week rows: monthcalendar
calendar.monthcalendar(year, month) returns the month as a list of weeks, and each week is a list of seven day numbers. Days that fall in the neighboring months appear as 0, so every week has exactly seven entries and the first week may start with zeros and the last week may end with them:
import calendar
for week in calendar.monthcalendar(2026, 11):
print(week)
print(calendar.monthcalendar(2027, 2))
The exact output:
[0, 0, 0, 0, 0, 0, 1]
[2, 3, 4, 5, 6, 7, 8]
[9, 10, 11, 12, 13, 14, 15]
[16, 17, 18, 19, 20, 21, 22]
[23, 24, 25, 26, 27, 28, 29]
[30, 0, 0, 0, 0, 0, 0]
[[1, 2, 3, 4, 5, 6, 7], [8, 9, 10, 11, 12, 13, 14], [15, 16, 17, 18, 19, 20, 21], [22, 23, 24, 25, 26, 27, 28]]
November 2026 needs six weeks because it starts on a Sunday, the last column of a Monday-first week, so the 1st sits alone at the end of the first row and the 30th sits alone at the start of the last. February 2027 is the tidy opposite: it starts on a Monday and has 28 days, so it fills exactly four weeks with no zeros at all. A grid display can render the zeros as blank cells, and a program that only wants real days can skip any entry equal to 0.
Iterating days and dates: the Calendar class
The Calendar class takes the first weekday as an argument and offers iterators that the module-level functions do not. itermonthdays yields every day number in the month's weeks, with 0 for the padding days. itermonthdates yields a datetime.date for every one of those same positions, with the padding positions filled by the real dates from the neighboring months. itermonthdays2 pairs each day number with its weekday:
import calendar
cal = calendar.Calendar(firstweekday=0)
print(list(cal.itermonthdays(2026, 11)))
dates = list(cal.itermonthdates(2026, 11))
print(dates[0], dates[6], dates[-1], len(dates))
print(list(cal.itermonthdays2(2026, 11))[:7])
The exact output:
[0, 0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 0, 0, 0, 0, 0, 0]
2026-10-26 2026-11-01 2026-12-06 42
[(0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5), (1, 6)]
Six weeks of seven positions make 42 entries, and the date form shows what the zeros hide: the first position is October 26, 2026, and the last is December 6, 2026. That makes itermonthdates the right choice when the padding days still need to display or compare as dates, and itermonthdays the right choice when padding should stay visibly empty. The first seven pairs from itermonthdays2 end with the pair for the 1st, day 1 with weekday 6, which is Sunday in the module numbering.
Printing a month: TextCalendar and HTMLCalendar
TextCalendar formats a month as plain text. Its constructor takes the first weekday, and formatmonth(year, month) returns the finished string, with a centered month and year heading, a two-letter weekday header row, and the days in columns. The HTMLCalendar class works the same way and returns an HTML table instead, for a month that belongs on a web page rather than in a terminal or a file:
import calendar
print(calendar.TextCalendar(0).formatmonth(2026, 11), end="")
print(calendar.TextCalendar(6).formatmonth(2027, 2), end="")
The exact output:
November 2026
Mo Tu We Th Fr Sa Su
1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30
February 2027
Su Mo Tu We Th Fr Sa
1 2 3 4 5 6
7 8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28
The two blocks differ only in the first-weekday argument, 0 for Monday and 6 for Sunday, and the change moves both the header order and every day's column. In the Sunday-first February, the 1st sits in the second column of its row, under Mo, because February 1, 2027 is a Monday and the row now starts a day earlier. The spacing is part of the output: single-digit days carry a leading space so the columns stay aligned, which is why copying this text into a fixed-width display keeps the grid intact.
Names and the module-wide first weekday
calendar.day_name is a sequence of the seven weekday names starting with Monday, and calendar.day_abbr holds their three-letter forms. calendar.month_name holds the month names with an empty string at index 0, so a month number indexes it directly with no adjustment, and calendar.month_abbr does the same for the short forms. Separately from any one class, calendar.setfirstweekday sets the first weekday for the module-level functions, and calendar.firstweekday reports the current setting:
import calendar
print(list(calendar.day_name))
print(list(calendar.month_name)[1:])
print(calendar.month_name[11], calendar.day_abbr[1])
print(calendar.firstweekday())
calendar.setfirstweekday(calendar.SUNDAY)
print(calendar.firstweekday())
print(calendar.monthcalendar(2027, 2))
print(calendar.month(2027, 2), end="")
calendar.setfirstweekday(calendar.MONDAY)
print(calendar.firstweekday())
The exact output:
['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
November Tue
0
6
[[0, 1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12, 13], [14, 15, 16, 17, 18, 19, 20], [21, 22, 23, 24, 25, 26, 27], [28, 0, 0, 0, 0, 0, 0]]
February 2027
Su Mo Tu We Th Fr Sa
1 2 3 4 5 6
7 8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28
0
Setting Sunday as the first weekday changes the module-level results that follow it: February 2027 now opens with a zero for the Sunday position before the Monday 1st, and calendar.month prints the Sunday-first header. The names do not move with that setting: day_name still starts with Monday, because the sequence is indexed by the weekday number, not by the display order. Code that changes the setting should set it back, as the last two lines do, because the setting is module-wide and later code in the same program will inherit whatever was left in place. A Calendar or TextCalendar object with its own first-weekday argument is the cleaner choice when only one view needs the change.
Which choice for which job
| Job | Choice | Why |
|---|---|---|
| The weekday of one date | weekday |
Returns Monday as 0 through Sunday as 6 for that single date |
| Whether a year is a leap year | isleap |
Applies the divide-by-4, 100, and 400 rule in one call |
| Leap days across a span of years | leapdays |
Counts them for the span instead of testing each year in a loop |
| A month's length and first weekday | monthrange |
Returns both, with February's length already leap-aware |
| A month arranged in weeks | monthcalendar or a Calendar iterator |
Week rows with 0 padding, or a flat stream of days or real dates |
| A month as text or HTML | TextCalendar or HTMLCalendar |
Formatted output with the first weekday chosen per object |
| A date object or date arithmetic | The datetime module |
calendar reports facts about days; it does not carry or subtract dates |
Checklist
- Remember the weekday numbering: Monday is 0 and Sunday is 6, and use the
calendar.MONDAYtocalendar.SUNDAYconstants in comparisons. - Use
isleapfor a single year instead of a divide-by-4 test, which gets 1900 and 2000 wrong. - Read a month's length from
monthrangeinstead of a hand-kept table, so February needs no special case. - Treat 0 in
monthcalendaranditermonthdaysas padding from a neighboring month, not as a real day. - Use
itermonthdateswhen the padding positions need real dates, and a per-object first weekday when only one view changes. - Set a module-wide first weekday back after changing it, or prefer a
Calendarobject that carries its own setting.
Related guides on this site
- Python datetime — date, time, and timedelta — the date objects
itermonthdatesyields, and the arithmetic this module leaves todatetime. - Python loops and conditionals — the loops that walk week rows, day iterators, and ranges of years.
- Python strings — slicing and methods — handling the formatted month text that
TextCalendarreturns. - Python textwrap — wrap, dedent, and shorten — shaping surrounding text when a printed month sits inside a wider report.
Sources
- Python Standard Library,
calendar—weekday,monthrange,monthcalendar,isleapandleapdays, theCalendar,TextCalendar, andHTMLCalendarclasses,firstweekdayandsetfirstweekday, and theday_nameandmonth_namesequences.
Keep Exploring
The full Python hub \u2014 language basics, the standard library, and data tools.
Every guide on the site in one list, grouped by topic.
Every browser-only checker and verifier on the site.
The C++, Python, Sysadmin, Rust, Go, and TypeScript hubs.