isocalendar() returns three numbers for the ISO 8601 calendar: the ISO year, the week number (1 to 52 or 53), and the weekday (Monday 1 to Sunday 7).
ISO weeks start on Monday, and week 1 is the week with the year's first Thursday, so a date in late December or early January can belong to the neighbouring ISO year. fromisocalendar() converts the triple back into a date.
date.isocalendar() is an instance method of datetime.date: call it on an existing object with dot notation, such as day.isocalendar(...). Import the class first, for example from datetime import date. The datetime class has a method with the same name. Since Python 3.9 the result is a named tuple (IsoCalendarDate) with year, week, and weekday attributes; earlier versions return a plain tuple.
Syntax
Call it with no arguments and unpack the result.
python
year, week, weekday = day.isocalendar()
Call
What it does
tuple(date(2024, 3, 15).isocalendar())
Returns (2024, 11, 5).
tuple(date(2024, 12, 30).isocalendar())
Returns (2025, 1, 1): already ISO year 2025.
tuple(date(2021, 1, 3).isocalendar())
Returns (2020, 53, 7): still the last week of 2020.
Unpacking or indexing ([1] for the week) works on every Python 3 version; the attribute names need 3.9+.
Method signatures
python
date.isocalendar()
datetime.isocalendar()
# returns: (year, week, weekday); a named tuple IsoCalendarDate in 3.9+
Parameters
isocalendar() takes no parameters.
Return Value
Return Value
Description
tuple of 3 ints
ISO year, ISO week number, and ISO weekday (1 = Monday).
Python Examples
Example 1 — Get the ISO Year, Week, and Weekday
Unpack the result for a Friday and build the standard YYYY-Www-D label.
python
from datetime import date
year, week, weekday = date(2024, 3, 15).isocalendar()
print(year, week, weekday)
print(f"{year}-W{week:02d}-{weekday}")
print(date(2024, 1, 1).isocalendar()[1])
Output
2024 11 5
2024-W11-5
1
How It Works
Three values. 15 March 2024 is in ISO week 11, and Friday is weekday 5.
ISO week label. The f-string builds the week-date notation used in reports and file names.
Index access.[1] picks the week; 1 January 2024 is a Monday, so it opens week 1.
Example 2 — Spot Dates in a Different ISO Year
Check four dates around New Year and compare the ISO year with the calendar year.
python
from datetime import date
for day in (date(2024, 12, 29), date(2024, 12, 30), date(2027, 1, 1), date(2027, 1, 3)):
iso_year, iso_week, _ = day.isocalendar()
print(day, "->", iso_year, iso_week)