ZetCode

Python ISO weeks

last modified November 19, 2026 Python 3.15

In this article we work with ISO 8601 week numbers in Python. Week numbers are common in business planning, payroll, and production schedules, where people speak of week 47 instead of a date.

ISO 8601 defines the rules: weeks begin on Monday, weekdays are numbered from 1 for Monday to 7 for Sunday, and week 1 of a year is the week that contains the year's first Thursday. A year therefore has 52 or 53 weeks. The date class of the datetime module supports these rules directly.

A first week number

The isocalendar method returns the ISO year, week, and weekday of a date.

first_week.py
from datetime import date

d = date(2026, 11, 19)
iso = d.isocalendar()

print(iso)
print(iso.year, iso.week, iso.weekday)

year, week, weekday = iso
print(f"{year}-W{week:02}-{weekday}")

November 19, 2026 is the Thursday of week 47. Since Python 3.9 the method returns a named tuple, so the fields are available by name or by unpacking. The last line prints the standard week-date notation.

$ python first_week.py
datetime.IsoCalendarDate(year=2026, week=47, weekday=4)
2026 47 4
2026-W47-4

Week 1

Because week 1 is the week with the first Thursday, it can begin in December of the previous year, and January 1 can belong to the last week of the previous year.

week_one.py
from datetime import date

for year in range(2024, 2030):
    jan1 = date(year, 1, 1)
    y, w, wd = jan1.isocalendar()
    week1 = date.fromisocalendar(year, 1, 1)
    print(f"{jan1} {jan1:%a}  is {y}-W{w:02}-{wd}   "
          f"week 1 of {year} starts {week1} {week1:%a}")

When January 1 falls on Monday to Thursday, it is in week 1. When it falls on Friday to Sunday, it belongs to week 52 or 53 of the previous ISO year: January 1, 2027 is in week 53 of 2026. The fromisocalendar method gives the Monday of week 1, which can be as early as December 29.

$ python week_one.py
2024-01-01 Mon  is 2024-W01-1   week 1 of 2024 starts 2024-01-01 Mon
2025-01-01 Wed  is 2025-W01-3   week 1 of 2025 starts 2024-12-30 Mon
2026-01-01 Thu  is 2026-W01-4   week 1 of 2026 starts 2025-12-29 Mon
2027-01-01 Fri  is 2026-W53-5   week 1 of 2027 starts 2027-01-04 Mon
2028-01-01 Sat  is 2027-W52-6   week 1 of 2028 starts 2028-01-03 Mon
2029-01-01 Mon  is 2029-W01-1   week 1 of 2029 starts 2029-01-01 Mon

The ISO year

The first field of isocalendar is the ISO year, which differs from the calendar year for a few days around New Year.

iso_year.py
from datetime import date, timedelta

for start in [date(2024, 12, 28), date(2026, 12, 28)]:
    for i in range(7):
        d = start + timedelta(days=i)
        y, w, wd = d.isocalendar()
        mark = "  <- ISO year differs" if y != d.year else ""
        print(f"{d} {d:%a}  {y}-W{w:02}-{wd}{mark}")
    print()

December 30 and 31, 2024 belong to week 1 of ISO year 2025, and January 1 to 3, 2027 to week 53 of ISO year 2026. A week number is meaningful only together with its ISO year. Combining d.year with the week number is a common bug that puts the first days of 2027 into week 53 of 2027, which does not exist.

$ python iso_year.py
2024-12-28 Sat  2024-W52-6
2024-12-29 Sun  2024-W52-7
2024-12-30 Mon  2025-W01-1  <- ISO year differs
2024-12-31 Tue  2025-W01-2  <- ISO year differs
2025-01-01 Wed  2025-W01-3
2025-01-02 Thu  2025-W01-4
2025-01-03 Fri  2025-W01-5

2026-12-28 Mon  2026-W53-1
2026-12-29 Tue  2026-W53-2
2026-12-30 Wed  2026-W53-3
2026-12-31 Thu  2026-W53-4
2027-01-01 Fri  2026-W53-5  <- ISO year differs
2027-01-02 Sat  2026-W53-6  <- ISO year differs
2027-01-03 Sun  2026-W53-7  <- ISO year differs

The dates of a week

The date.fromisocalendar method, the inverse of isocalendar, turns an ISO year, week, and weekday into a date.

week_dates.py
from datetime import date, timedelta


def week_range(year, week):
    monday = date.fromisocalendar(year, week, 1)
    return monday, monday + timedelta(days=6)


print(date.fromisocalendar(2026, 47, 4))

for year, week in [(2026, 1), (2026, 47), (2026, 53), (2027, 1)]:
    first, last = week_range(year, week)
    print(f"{year}-W{week:02}  {first:%a %d %b %Y} - {last:%a %d %b %Y}")


def week_start(d):
    return d - timedelta(days=d.weekday())


print(week_start(date(2026, 11, 19)))
print(week_start(date(2027, 1, 3)))

The week_range function returns the Monday and Sunday of a week. Week 1 of 2026 begins on December 29, 2025, and week 53 ends on January 3, 2027. To get the Monday of the week of any date, the week_start function subtracts the weekday; it does not need the week number at all.

$ python week_dates.py
2026-11-19
2026-W01  Mon 29 Dec 2025 - Sun 04 Jan 2026
2026-W47  Mon 16 Nov 2026 - Sun 22 Nov 2026
2026-W53  Mon 28 Dec 2026 - Sun 03 Jan 2027
2027-W01  Mon 04 Jan 2027 - Sun 10 Jan 2027
2026-11-16
2026-12-28

Formatting week numbers

The strftime method has three sets of week directives, and only one of them follows ISO 8601.

format_weeks.py
from datetime import date

dates = [date(2026, 1, 1), date(2026, 1, 4), date(2026, 1, 5),
         date(2026, 11, 19), date(2026, 12, 31), date(2027, 1, 1),
         date(2027, 1, 4)]

print("date        ISO %G-W%V-%u   %Y %W   %Y %U")
for d in dates:
    iso = d.strftime("%G-W%V-%u")
    monday = d.strftime("%Y %W")
    sunday = d.strftime("%Y %U")
    print(f"{d} {d:%a}  {iso:12}    {monday}    {sunday}")

print(date(2026, 11, 19).strftime("%G%V"))

The ISO directives are %G for the ISO year, %V for the ISO week, and %u for the ISO weekday. The %W directive counts weeks starting on Monday and %U weeks starting on Sunday; both start at week 00 with the days before the first Monday or Sunday of the year, and both use the calendar year. They agree with ISO weeks in some years and are off by one in others, as in 2026. Never combine %Y with %V.

$ python format_weeks.py
date        ISO %G-W%V-%u   %Y %W   %Y %U
2026-01-01 Thu  2026-W01-4      2026 00    2026 00
2026-01-04 Sun  2026-W01-7      2026 00    2026 01
2026-01-05 Mon  2026-W02-1      2026 01    2026 01
2026-11-19 Thu  2026-W47-4      2026 46    2026 46
2026-12-31 Thu  2026-W53-4      2026 52    2026 52
2027-01-01 Fri  2026-W53-5      2027 00    2027 00
2027-01-04 Mon  2027-W01-1      2027 01    2027 01
202647

Parsing week dates

Week dates can be parsed with strptime and, since Python 3.11, with fromisoformat.

parse_weeks.py
from datetime import date, datetime

print(datetime.strptime("2026-W47-4", "%G-W%V-%u").date())
print(datetime.strptime("2026 47 1", "%G %V %u").date())

print(date.fromisoformat("2026-W47-4"))
print(date.fromisoformat("2026-W47"))
print(date.fromisoformat("2026W474"))

tests = [
    ("2026-W47", "%G-W%V"),
    ("2026-W47-4", "%Y-W%V-%u"),
    ("2026-W54-1", "%G-W%V-%u"),
]

for text, fmt in tests:
    try:
        print(datetime.strptime(text, fmt))
    except ValueError as e:
        print(f"{text!r} {fmt!r}: {e}")

The strptime method needs %G, %V, and a weekday together; a week without a day is rejected, and so is %Y with %V. The fromisoformat method accepts the extended form 2026-W47-4, the basic form 2026W474, and a week without a day, which means its Monday. Week 54 never exists, so the last string does not match.

$ python parse_weeks.py
2026-11-19
2026-11-16
2026-11-19
2026-11-16
2026-11-19
'2026-W47' '%G-W%V': ISO year directive '%G' must be used with the ISO week directive '%V' and a weekday directive ('%A', '%a', '%w', or '%u').
'2026-W47-4' '%Y-W%V-%u': ISO week directive '%V' is incompatible with the year directive '%Y'. Use the ISO year '%G' instead.
'2026-W54-1' '%G-W%V-%u': time data '2026-W54-1' does not match format '%G-W%V-%u'

Years with 53 weeks

December 28 always lies in the last week of its ISO year, so its week number tells how many weeks the year has.

long_years.py
import calendar
from datetime import date


def weeks_in_year(year):
    return date(year, 12, 28).isocalendar().week


long_years = [y for y in range(2020, 2041) if weeks_in_year(y) == 53]
print(long_years)

for year in long_years:
    jan1 = date(year, 1, 1)
    leap = "leap year" if calendar.isleap(year) else ""
    print(year, f"starts on {jan1:%A}", leap)

count = sum(weeks_in_year(y) == 53 for y in range(2001, 2401))
print(count, "of 400 years have 53 weeks")

try:
    date.fromisocalendar(2025, 53, 1)
except ValueError as e:
    print("ValueError:", e)

A year has 53 weeks when it starts on a Thursday, or when it is a leap year starting on a Wednesday. That happens 71 times in the 400-year cycle of the Gregorian calendar, roughly every five or six years. The leap year check uses the calendar module. Asking for week 53 of a 52-week year raises ValueError.

$ python long_years.py
[2020, 2026, 2032, 2037]
2020 starts on Wednesday leap year
2026 starts on Thursday 
2032 starts on Thursday leap year
2037 starts on Thursday 
71 of 400 years have 53 weeks
ValueError: Invalid week: 53

The weeks of a month

ISO weeks do not respect month boundaries. A month touches four to six weeks, and the first and last of them are often partial.

month_weeks.py
from datetime import date, timedelta


def weeks_of_month(year, month):
    d = date(year, month, 1)
    weeks = []
    while d.month == month:
        key = d.isocalendar()[:2]
        if key not in weeks:
            weeks.append(key)
        d += timedelta(days=1)
    return weeks


for year, week in weeks_of_month(2026, 11):
    monday = date.fromisocalendar(year, week, 1)
    days = [monday + timedelta(days=i) for i in range(7)]
    inside = [d for d in days if d.month == 11]
    print(f"W{week:02}  {inside[0]:%d %b} - {inside[-1]:%d %b}  {len(inside)} day{"s" * (len(inside) > 1)}")

print(len(weeks_of_month(2026, 11)), len(weeks_of_month(2026, 2)))

The function walks through the days of the month and collects the distinct (year, week) pairs in order. November 2026 touches six weeks, two of them with a single day; February 2026 touches five. A monthly report built from weekly figures has to split such weeks.

$ python month_weeks.py
W44  01 Nov - 01 Nov  1 day
W45  02 Nov - 08 Nov  7 days
W46  09 Nov - 15 Nov  7 days
W47  16 Nov - 22 Nov  7 days
W48  23 Nov - 29 Nov  7 days
W49  30 Nov - 30 Nov  1 day
6 5

A weekly report

Grouping data by week is the most common use of week numbers. The program sums sales from a CSV file per ISO week.

weekly_report.py
import csv
from collections import defaultdict
from datetime import date

totals = defaultdict(float)
counts = defaultdict(int)

with open("sales.csv", newline="") as f:
    for row in csv.DictReader(f):
        d = date.fromisoformat(row["date"])
        year, week, _ = d.isocalendar()
        totals[(year, week)] += float(row["amount"])
        counts[(year, week)] += 1

for (year, week), total in sorted(totals.items()):
    monday = date.fromisocalendar(year, week, 1)
    print(f"{year}-W{week:02}  from {monday:%d %b}  "
          f"{counts[(year, week)]} sales  {total:>8.2f}")

The input file contains a date and an amount on each line:

date,amount
2026-10-30,120.50
2026-11-02,80.00
...
2026-12-31,500.00
2027-01-02,75.00
2027-01-04,40.00

The key of the dictionaries is the (year, week) pair from isocalendar. The sales of December 31, 2026 and January 2, 2027 land in the same week, 2026-W53. Sorting the keys sorts the weeks chronologically, including across years.

$ python weekly_report.py
2026-W44  from 26 Oct  1 sales    120.50
2026-W45  from 02 Nov  3 sales    335.25
2026-W46  from 09 Nov  2 sales    114.90
2026-W47  from 16 Nov  2 sales    364.40
2026-W53  from 28 Dec  2 sales    575.00
2027-W01  from 04 Jan  1 sales     40.00

Counting and adding weeks

Arithmetic on week numbers is best done through dates, because the number of weeks per year varies.

weeks_between.py
from datetime import date, timedelta


def monday_of(d):
    return d - timedelta(days=d.weekday())


def weeks_between(a, b):
    return (monday_of(b) - monday_of(a)).days // 7


def add_weeks(year, week, n):
    monday = date.fromisocalendar(year, week, 1) + timedelta(weeks=n)
    return monday.isocalendar()[:2]


start = date(2026, 11, 19)
for end in [date(2026, 11, 22), date(2026, 11, 23), date(2027, 1, 4),
            date(2027, 11, 19)]:
    print(f"{start} -> {end}  week numbers apart: {weeks_between(start, end):2}"
          f"  full weeks: {(end - start).days // 7}")

print(add_weeks(2026, 47, 10))
print(add_weeks(2026, 50, 4))
print(add_weeks(2027, 2, -2))

The weeks_between function compares the Mondays of two dates, so Thursday and the next Monday are one week apart, although less than a full week has passed. The add_weeks function converts a week to its Monday, adds a timedelta, and converts back. Ten weeks after 2026-W47 is 2027-W04, and two weeks before 2027-W02 is 2026-W53. Adding to the week number directly would produce invalid weeks such as 2026-W57.

$ python weeks_between.py
2026-11-19 -> 2026-11-22  week numbers apart:  0  full weeks: 0
2026-11-19 -> 2026-11-23  week numbers apart:  1  full weeks: 0
2026-11-19 -> 2027-01-04  week numbers apart:  7  full weeks: 6
2026-11-19 -> 2027-11-19  week numbers apart: 52  full weeks: 52
(2027, 4)
(2027, 1)
(2026, 53)

Source

datetime – date.isocalendar

ISO week date – Wikipedia

In this article we have worked with ISO week numbers in Python. See also Python datetime, Python timedelta, Python calendar, and Python parse dates.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.