Holidays

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

• pip install holidays Install latest version

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

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))}")