Introduction

There is no single universally "correct" week number for a date until you decide which calendar convention you mean. The most common source of bugs is mixing ISO week numbering with locale-specific systems such as US Sunday-based week numbering and expecting them to agree.

ISO Week Numbers vs Locale Week Numbers

The ISO 8601 system is the standard most developers want when they say week number. In ISO rules:

• the week starts on Monday
• week 1 is the week containing the first Thursday of the year
• some dates near January 1 can belong to the previous ISO year
• some dates near December 31 can belong to the next ISO year

That last point is what surprises people. For example, a date in early January may still be part of ISO week 52 or 53 of the previous year.

Other systems use different rules. In many US-style conventions:

• the week starts on Sunday
• week numbering is anchored differently around January 1

Those systems produce different answers for the same date, and neither answer is "wrong" without context.

The Safest Answer in Python

If you need ISO week numbers in Python, use the standard library directly:

1from datetime import date
2
3d = date(2021, 1, 1)
4iso_year, iso_week, iso_weekday = d.isocalendar()
5
6print(iso_year, iso_week, iso_weekday)

For January 1, 2021, this returns ISO year 2020, ISO week 53, and weekday 5. That is correct under ISO 8601 even though the calendar year is 2021.

Why strftime Can Be Confusing

Python also exposes strftime, but directives such as %U and %W are not the same as ISO week numbering.

• '%U uses Sunday as the first day of the week'
• '%W uses Monday as the first day of the week'
• neither one fully matches ISO semantics the way isocalendar() does

Example:

1from datetime import date
2
3d = date(2021, 1, 1)
4print(d.strftime("%U"))
5print(d.strftime("%W"))
6print(d.isocalendar().week)

These results can differ, and that is expected.

Implementing ISO Logic Manually

If you ever need to implement ISO week rules yourself, the key idea is to anchor the week to Thursday. A date belongs to the ISO week-year of the Thursday in its week.

That is why dates around New Year’s are tricky. The calculation is not based only on the date’s calendar year; it depends on which Thursday the week contains.

In most application code, manual implementation is a mistake. Use built-in date libraries unless you have a very strong reason not to.

Cross-Language Caution

The same ambiguity exists in other languages and databases:

• Java has ISO-aware date APIs in java.time
• .NET has explicit ISO week helpers in newer libraries
• SQL databases often provide both ISO and locale-style week functions

The bug pattern is always similar: one system uses ISO, another uses locale defaults, and reports stop matching around year boundaries.

Testing Edge Cases

When week numbers matter for business logic, test dates near the edges of the year:

• January 1
• January 4
• December 28
• December 31
• leap years

These are the dates most likely to expose incorrect assumptions.

Common Pitfalls

The biggest mistake is asking for the "correct" week number without defining the week standard first. ISO and locale week systems are both valid.

Another issue is using %U or %W when the business actually wants ISO 8601 weeks.

Teams also forget that ISO week-year and calendar year are not always the same value. That leads to reporting bugs where week numbers appear to belong to the wrong year.

Finally, do not reimplement week logic unless your platform genuinely lacks the correct API. Date rules are harder to get right than they look.

Summary

• Week numbers are only meaningful once you define the calendar convention.
• ISO 8601 is the standard most technical systems mean by week number.
• In Python, date.isocalendar() is the safest way to get ISO week data.
• '%U and %W are not the same as ISO week numbering.'
• Test year-boundary dates because that is where most week-number bugs appear.