Introduction

Getting a week number in Python is easy once you decide which week-numbering system you actually need. The main source of confusion is that ISO weeks, Sunday-based weeks, and Monday-based weeks do not always agree, especially around New Year.

Use isocalendar() for ISO week numbers

If you want the ISO-8601 week number, use date.isocalendar(). This is usually the safest default for business reporting and calendar-style logic.

1from datetime import date
2
3d = date(2026, 1, 1)
4iso = d.isocalendar()
5
6print(iso.year)
7print(iso.week)
8print(iso.weekday)

In current Python versions, isocalendar() returns a named tuple-like object, so iso.week is clearer than indexing into position 1.

ISO weeks follow these rules:

• Monday is the first day of the week
• week 1 is the week containing the first Thursday of the year

That means a date in early January can belong to the final ISO week of the previous ISO year.

Compare %U and %W in strftime

Python also exposes week numbers through strftime, but these formats use different conventions:

• '%U counts weeks starting on Sunday'
• '%W counts weeks starting on Monday'

Example:

1from datetime import datetime
2
3dt = datetime(2026, 1, 1)
4
5print(dt.strftime("%U"))
6print(dt.strftime("%W"))
7print(dt.isocalendar().week)

These results can differ. That does not mean one is wrong. It means they answer different calendar questions.

Also note that %U and %W return strings such as "00" or "01". Convert them if you need integers:

week_u = int(dt.strftime("%U"))
week_w = int(dt.strftime("%W"))

Boundary dates are where the differences matter

Dates near the start and end of a year are the tricky ones.

1from datetime import date
2
3for d in [
4    date(2025, 12, 29),
5    date(2025, 12, 31),
6    date(2026, 1, 1),
7    date(2026, 1, 4),
8    date(2026, 1, 5),
9]:
10    print(d, d.isocalendar(), d.strftime("%U"), d.strftime("%W"))

A date can belong to calendar year 2026 while still belonging to ISO week year 2025. If the program groups data by week number, storing only the week and not the associated week year can create ambiguous data.

Build a helper and keep one rule everywhere

If your application uses week numbers repeatedly, wrap the chosen rule in a helper so the whole codebase stays consistent.

1from datetime import date
2
3def iso_week_info(d: date) -> tuple[int, int]:
4    iso = d.isocalendar()
5    return iso.year, iso.week
6
7
8print(iso_week_info(date(2026, 1, 1)))

This is better than scattering %U, %W, and isocalendar() calls across different files with no explicit policy.

Pandas makes vectorized week extraction easy

If you are working with many dates in a DataFrame, Pandas can expose ISO week information efficiently.

1import pandas as pd
2
3dates = pd.to_datetime(["2025-12-31", "2026-01-01", "2026-01-05"])
4iso = dates.isocalendar()
5
6print(iso)
7print(iso["week"])

This is especially useful in reporting pipelines, analytics, and time-series grouping.

Pick the week system that matches the domain

Use ISO weeks when:

• business reports require ISO-style week numbering
• consistency across countries matters
• the surrounding system already uses ISO calendars

Use %U or %W only when your domain specifically wants those rules. The problem is not choosing the "wrong" one in the abstract. The problem is mixing several definitions in one application without realizing it.

Common Pitfalls

The biggest mistake is using the week number alone without its associated year system. Week 1 without the corresponding calendar rule and year is often ambiguous.

Another issue is assuming %U, %W, and ISO week numbers should always match. They do not, especially near New Year.

Developers also forget that strftime("%U") and strftime("%W") return strings. That can create subtle sorting or comparison bugs if they are treated as integers later.

Finally, always test dates at year boundaries if week numbers drive reporting or billing logic. Those boundary cases are where most bugs surface.

Summary

• Use isocalendar().week when you need ISO week numbers.
• '%U and %W follow different rules and can disagree with ISO weeks.'
• Dates near New Year can belong to a different ISO week year than their calendar year.
• Store both the week number and its associated year when grouping by week.
• Pick one week-numbering policy for the whole application and use it consistently.