Holidays

0.93 verified Tue May 12 auth: no python install: verified

The Python `holidays` library (currently v0.93) is an Open World Holidays Framework that provides a fast and efficient way to determine if a specific date is a public holiday in various countries and subdivisions. It is actively maintained with frequent, approximately bi-weekly, releases adding new countries, regions, and localization support. It is commonly used in scheduling, automation systems, and applications requiring holiday awareness.

pip install holidays

Common errors

error ModuleNotFoundError: No module named 'holidays' ↓

cause The `holidays` library is not installed in the active Python environment, or the environment where it's installed is not being used.

fix

Ensure the library is installed in your current environment by running: pip install holidays

error ModuleNotFoundError: No module named 'holidays.countries' ↓

cause When building an executable with PyInstaller, it may fail to automatically detect and include all dynamically imported country submodules of the `holidays` library.

fix

Explicitly tell PyInstaller to include the necessary submodules using hidden imports, e.g.: pyinstaller your_script.py --hidden-import holidays.countries --hidden-import holidays.financial (add more as needed)

error AttributeError: module 'holidays' has no attribute 'i' (or similar like 'US' when using a variable) ↓

cause You are trying to access a country-specific holiday class (e.g., `holidays.US`) dynamically using a string variable directly as an attribute, which Python does not support this way.

fix

Use the holidays.country_holidays() factory function or getattr() for dynamic country access: country_code = 'US'; us_holidays = holidays.country_holidays(country_code) or us_holidays = getattr(holidays, country_code)()

error TypeError: 'module' object is not callable ↓

cause The `holidays` module itself is being called as a function (e.g., `holidays()`) instead of initializing a specific country's holiday object or using a factory function.

fix

Initialize a specific country's holidays, for example: us_holidays = holidays.US() or us_holidays = holidays.country_holidays('US')

error NotImplementedError ↓

cause The requested country or subdivision's holiday data is not yet implemented or supported by the installed `holidays` library version.

fix

Check the official documentation or holidays.list_supported_countries() for available countries and subdivisions; consider contributing the missing data or upgrading the library.

Warnings

breaking Python 3.9 support was officially dropped in version 0.84 of the library. ↓

fix Upgrade your Python environment to version 3.10 or newer, or pin the `holidays` dependency to `<0.84` if Python 3.9 is required.

gotcha When querying holidays for countries with subdivisions (states, provinces), not specifying the `state` or `prov` parameter will only return national holidays, potentially missing relevant regional holidays. For example, `holidays.UnitedStates()` will not include state-specific holidays like California's Diwali. ↓

fix Always specify the `state` or `prov` parameter (e.g., `holidays.UnitedStates(state='CA')`) when you need subdivision-specific holidays.

gotcha The library includes 'observed' holidays (e.g., when a holiday falls on a weekend, the preceding or following weekday is observed) by default (`observed=True`). This might not be desired if only the official fixed date is needed. ↓

fix To disable observed holidays, initialize the country object with `observed=False` (e.g., `holidays.UnitedStates(observed=False)`).

deprecated The project plans to adopt a loose form of Semantic Versioning (SemVer) starting from version 1.0. This means future major versions (1.x.x) may introduce backward-incompatible API changes. While not yet a breaking change, it's a strong advisory. ↓

fix It is highly recommended to pin your `holidays` dependency to avoid unexpected upgrades to version 1.0 or later that might contain breaking changes. For example, use `holidays<1.0` or `holidays==0.93`.

gotcha Holiday names are returned in a default language (often English or the country's primary language) unless explicitly specified. This can lead to unexpected language output if localization is important. ↓

fix Specify the `language` parameter during instantiation to get holiday names in a desired locale (e.g., `holidays.Germany(language='de')`). Consult the documentation for supported languages per country.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.29s 29.0M

3.10 alpine (musl) - - 0.24s 28.6M

3.10 slim (glibc) wheel 2.1s 0.17s 29M

3.10 slim (glibc) - - 0.19s 29M

3.11 alpine (musl) wheel - 0.98s 32.2M

3.11 alpine (musl) - - 0.96s 31.7M

3.11 slim (glibc) wheel 2.2s 0.79s 33M

3.11 slim (glibc) - - 0.80s 32M

3.12 alpine (musl) wheel - 0.72s 23.8M

3.12 alpine (musl) - - 0.75s 23.3M

3.12 slim (glibc) wheel 2.1s 0.76s 24M

3.12 slim (glibc) - - 0.78s 24M

3.13 alpine (musl) wheel - 0.70s 23.5M

3.13 alpine (musl) - - 0.74s 22.9M

3.13 slim (glibc) wheel 2.1s 0.76s 24M

3.13 slim (glibc) - - 0.78s 23M

3.9 alpine (musl) wheel - 0.11s 27.3M

3.9 alpine (musl) - - 0.10s 27.3M

3.9 slim (glibc) wheel 2.4s 0.08s 28M

3.9 slim (glibc) - - 0.08s 28M

Imports

holidays
```
import holidays
```
The primary module import to access country-specific holiday classes or the generic HolidayBase.
UnitedStates
```
import holidays
us_holidays = holidays.UnitedStates(years=[2026])
```
To get holidays for a specific country, instantiate its class directly, optionally passing years and other parameters.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to instantiate the holidays object for a specific country (United States) and subdivision (California), check if a date is a holiday, and retrieve its name. It also shows how to get holiday names in a specific language (German for Germany).

from datetime import date
import holidays

# Get all US federal holidays for a specific year
us_holidays_2026 = holidays.UnitedStates(years=[2026])

print(f"Is New Year's Day (Jan 1, 2026) a holiday? {date(2026, 1, 1) in us_holidays_2026}")
print(f"Holiday name for Jan 1, 2026: {us_holidays_2026.get(date(2026, 1, 1))}")

# Get California state holidays for a year
ca_holidays_2026 = holidays.UnitedStates(years=[2026], state='CA')

# Check a specific date (e.g., California's observed Juneteenth, if applicable)
example_date = date(2026, 6, 19) # Juneteenth National Independence Day
print(f"Is {example_date} a holiday in California? {example_date in ca_holidays_2026}")
if example_date in ca_holidays_2026:
    print(f"Holiday name: {ca_holidays_2026.get(example_date)}")

# Get holidays in German for Germany
de_holidays_2026_de = holidays.Germany(years=[2026], language='de')
print(f"German holiday name for Jan 1, 2026: {de_holidays_2026_de.get(date(2026, 1, 1))}")