ISO Week Number in Python

Updated: May 2026

Python's standard library handles ISO weeks natively. The isocalendar() method on date and datetime objects returns the ISO year, ISO week number, and ISO weekday in one call — correctly handling all year-boundary edge cases.

Verify week numbers online →

Free · No upload · 100% in-browser

The standard method: isocalendar()

Since Python 3.9, isocalendar() returns a named tuple IsoCalendarDate(year, week, weekday). In earlier versions it returns a plain tuple. Both work the same way.

from datetime import date

d = date(2026, 5, 28)
iso = d.isocalendar()
print(iso.year)     # 2026
print(iso.week)     # 22
print(iso.weekday)  # 4 (Thursday)

The weekday field uses ISO numbering: 1 = Monday through 7 = Sunday. This is different from date.weekday(), which returns 0 for Monday, and from date.isoweekday(), which matches the ISO numbering (1–7).

Always use isocalendar().year rather than date.year when you need the ISO year. For December 31 and early January dates, these two values can differ by one.

Using strftime with %V and %G

The strftime format supports ISO week directives:

d = date(2026, 12, 31)
print(d.strftime("%G-W%V-%u"))  # 2026-W53-4
print(d.strftime("%Y-W%W"))     # Wrong at year boundaries!

%V — ISO week number (01–53), Monday as first day.
%G — ISO year (the year that owns the week — may differ from calendar year).
%u — ISO weekday (1 = Monday, 7 = Sunday).
%W — simple week number with Monday start but non-ISO week 1 definition — avoid for ISO work.
%U — simple week number with Sunday start — not ISO.

Parsing an ISO week date string

To convert an ISO week string like "2026-W22-4" back to a date object:

from datetime import date

iso_string = "2026-W22-4"
d = date.fromisocalendar(2026, 22, 4)
print(d)  # 2026-05-28

# From string:
year, week, day = (int(x) for x in iso_string.replace("W","").split("-"))
d = date.fromisocalendar(year, week, day)
print(d)  # 2026-05-28

date.fromisocalendar(year, week, day) is available since Python 3.8. It raises ValueError for invalid combinations, such as week 53 in a 52-week year.

Getting the Monday of an ISO week

To find the Monday (first day) of a given ISO year and week:

from datetime import date

def iso_week_monday(iso_year, iso_week):
    return date.fromisocalendar(iso_year, iso_week, 1)

print(iso_week_monday(2026, 22))  # 2026-05-25

To get the full week range (Monday to Sunday):

from datetime import date, timedelta

def iso_week_range(iso_year, iso_week):
    monday = date.fromisocalendar(iso_year, iso_week, 1)
    sunday = monday + timedelta(days=6)
    return monday, sunday

Counting how many ISO weeks in a year

A year has 53 ISO weeks when December 28 belongs to week 53. December 28 is always in the last ISO week of the year:

def iso_weeks_in_year(year):
    return date(year, 12, 28).isocalendar().week  # 52 or 53