Python date.isocalendar() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
date method

Definition

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()
CallWhat 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 ValueDescription
tuple of 3 intsISO 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])

How It Works

  1. Three values. 15 March 2024 is in ISO week 11, and Friday is weekday 5.
  2. ISO week label. The f-string builds the week-date notation used in reports and file names.
  3. 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)

How It Works

  1. Sunday ends a week. 29 December 2024 is a Sunday, the last day of week 52.
  2. Early start. Monday 30 December 2024 already opens week 1 of ISO year 2025.
  3. Late finish. 1 to 3 January 2027 still belong to week 53 of 2026, because that week holds 2026's last Thursday.

Example 3 — Count Orders per ISO Week

Use the (year, week) pair as a dictionary key to group dates.

python
from datetime import date

orders = [date(2024, 3, 11), date(2024, 3, 15), date(2024, 3, 17), date(2024, 3, 18)]
weeks = {}
for day in orders:
    key = day.isocalendar()[:2]
    weeks[key] = weeks.get(key, 0) + 1
print(weeks)

How It Works

  1. Year and week together. Slicing [:2] keeps the ISO year and week, so weeks from different years never mix.
  2. Monday to Sunday. 11, 15, and 17 March fall in week 11; Monday 18 March starts week 12.
  3. Counting with get(). weeks.get(key, 0) + 1 starts each new week at zero.

Frequently Asked Questions

Use day.isocalendar()[1], or unpack year, week, weekday = day.isocalendar().
ISO week 1 is the week containing the first Thursday of the new year, so it can start in late December.
Yes on Python 3.9+, where the result is a named tuple. Use [1] for older versions.
isocalendar() follows ISO 8601 (Monday weeks, first-Thursday rule). %U counts Sunday-based weeks from the first Sunday, starting at week 00.
Use date.fromisocalendar(year, week, weekday) on Python 3.8+.

Next: datetime.isoformat()

Return ISO 8601 text such as 2024-03-15T10:30:45+05:30, with sep and timespec options.

isoformat() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful