Install & Compatibility
Where this runs
tested against v0.103 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.646s · 29.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.600s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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))}")
Debug
Known issues
breakingPython 3.9 support was officially dropped in version 0.84 of the library.fixUpgrade your Python environment to version 3.10 or newer, or pin the `holidays` dependency to `<0.84` if Python 3.9 is required.
affects: >=0.84
gotchaWhen 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.fixAlways specify the `state` or `prov` parameter (e.g., `holidays.UnitedStates(state='CA')`) when you need subdivision-specific holidays.
affects: All versions
gotchaThe 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.fixTo disable observed holidays, initialize the country object with `observed=False` (e.g., `holidays.UnitedStates(observed=False)`).
affects: All versions
deprecatedThe 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.fixIt 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`.
affects: All v0.x versions
gotchaHoliday 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.fixSpecify 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'holidays'
The `holidays` library is not installed in the active Python environment, or the environment where it's installed is not being used.
fixEnsure the library is installed in your current environment by running: `pip install holidays`
ModuleNotFoundError: No module named 'holidays.countries'
When building an executable with PyInstaller, it may fail to automatically detect and include all dynamically imported country submodules of the `holidays` library.
fixExplicitly 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)
AttributeError: module 'holidays' has no attribute 'i' (or similar like 'US' when using a variable)
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.
fixUse 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)()`
TypeError: 'module' object is not callable
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.
fixInitialize a specific country's holidays, for example: `us_holidays = holidays.US()` or `us_holidays = holidays.country_holidays('US')` NotImplementedError
The requested country or subdivision's holiday data is not yet implemented or supported by the installed `holidays` library version.
fixCheck the official documentation or `holidays.list_supported_countries()` for available countries and subdivisions; consider contributing the missing data or upgrading the library.
Upgrade
Version history
0.103latest on PyPI · released Aug 17, 2026
Audit
Dependencies
No dependency data recorded yet.