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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
List all Python tutorials.