holidays

holidays is a Python library that generates government-designated public holidays for hundreds of countries and their subdivisions (states, provinces, regions) on demand. It is built to make checking whether a given date is a holiday as fast and flexible as possible.

Holidays are computed lazily per year, support multiple languages and categories (public, bank, school, and more), and behave like a Python dict keyed by date, so membership tests and lookups are simple and efficient. It covers a very large and continually growing set of national and regional calendars.

What You Get

• Holiday calendars for hundreds of countries and their subdivisions.
• A dict-like API where date in holidays is a fast membership test.
• Multi-language holiday names and multiple holiday categories (public, bank, school, etc.).
• Lazy, per-year generation that scales to arbitrary date ranges without precomputation.

Common Use Cases

• Determining whether a date is a public holiday for a given country or region.
• Computing business-day offsets that skip weekends and holidays.
• Localizing holiday names for calendars, scheduling, and payroll systems.

Under The Hood

Architecture

The package builds each country as a subclass of a HolidayBase dict (under holidays/countries and holidays/financial), where _populate(year) is called lazily the first time a year is accessed to insert that year’s holidays. Calendar helpers (Gregorian, plus Islamic, Hebrew, and other astronomical/lunisolar calendars under holidays/calendars) compute movable feast dates.

Tech Stack

Pure Python (3.9+) with minimal runtime dependencies (primarily python-dateutil), packaged with uv/hatch. Extensive per-country test suites run under pytest, with Ruff and mypy for quality, and documentation on Read the Docs.

Code Quality

Code quality is high: an exhaustive tests tree mirrors every country module, Ruff linting and mypy typing are enforced, a SECURITY.md and contribution guides are present, and CI runs on every change. The 337-contributor project maintains snapshots to guard against regressions.

API Design

The API is remarkably approachable: holidays.country_holidays('US') (or holidays.US()) returns a dict-like object you query with in or .get(). Optional arguments select subdivisions, years, language, and categories, so the common case is one line while advanced needs remain expressible.