---
id: epiweeks
version: "2.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# epiweeks — Epidemiological weeks calculation based on CDC and ISO week numbering systems

License: permissive · Maintenance: active · Downloads: 187.7K/mo

## What it is and what it does

EpiWeeks is a Python package for calculating epidemiological weeks according to two standards: the US CDC's MMWR (Morbidity and Mortality Weekly Report) system and the ISO week numbering system. It provides week-to-date conversions, date-to-week lookups, and iteration over weeks within a year, all validated against CDC reference data. The package is designed for disease surveillance, public health reporting, and epidemiological research where precise week boundaries matter.

The package offers a clean API with Week and Year objects that support comparison, arithmetic (addition and subtraction), and containment checks. It includes full type annotations, comprehensive input validation, and zero runtime dependencies, making it straightforward to integrate into public health applications or data pipelines.

Use it for:

- Generate CDC MMWR week boundaries for disease surveillance reports and epidemiological data aggregation.
- Convert between calendar dates and epidemiological week numbers for public health data analysis.
- Iterate over all weeks in a year to populate surveillance dashboards or export weekly summaries.
- Validate and normalize week-based data from multiple public health sources using a single standard.
- Build time-series analyses aligned to epidemiological weeks rather than calendar months or ISO weeks.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Calculates epidemiological weeks using US CDC (MMWR) and ISO week numbering systems, with validated accuracy against CDC reference data.

Yes. Active maintenance, zero dependencies, permissive license, production-stable status, and validated accuracy against CDC data make this a reliable choice for any epidemiological or public health application that needs precise week calculations. The low install friction and broad Python version support (3.10–3.14) add to its appeal.

## Install

pip install epiweeks
uv add epiweeks
poetry add epiweeks

## Installing epiweeks

Before you install: Low friction: pure Python wheel with zero runtime dependencies and active maintenance. Last commit 2026-08-06, production-stable status, supports Python 3.10 through 3.14.

License in practice: MIT license (permissive): you may use, modify, and distribute this package freely in commercial and private projects, with minimal restrictions.

Quickstart:

from epiweeks import Week, Year

week = Week(2019, 1)
print(week.enddate())
# 2019-01-05

for week in Year(2019).iterweeks():
    print(week.enddate())

Requires Python 3.10 or later.

Verify before relying:

- Whether CDC reference validation covers all edge cases or only specific year ranges
- Performance characteristics when iterating large numbers of weeks or years

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 187.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

epidemiological week calculation, CDC MMWR week numbering, ISO week calculation, disease surveillance weeks, public health week dates, epiweek calendar, week start end dates, epidemiology, public-health, calendar

[View on SkillFed](https://skillfed.io/packages/epiweeks) · [View on PyPI](https://pypi.org/project/epiweeks/)