holidays — Python Holiday Library

Overview

holidays is a Python library that generates country- and subdivision-specific sets of government-designated holidays on the fly. It covers 249 countries (ISO 3166-1) and supports subdivisions (states, provinces, regions) via ISO 3166-2 codes.

The central object is HolidayBase, which behaves like a Python dict mapping date → holiday name. All examples below can be run directly in the shell:

python <<'EOF'
# your code here
EOF
# OR (if the package is installed via uv)
uv run - <<EOF
# your code here
EOF

Installation

IMPORTANT: Always use a virtual environment or --break-system-packages flag.

pip install holidays --break-system-packages

For production use, pin to a specific version:

pip install holidays==0.58 --break-system-packages

Quick Reference

Core API

country_holidays() — Main Function

country_holidays(
    country,          # ISO 3166-1 alpha-2 code, e.g. 'US', 'GB', 'DE'
    subdiv=None,      # ISO 3166-2 subdivision code, e.g. 'CA', 'TX', 'BY'
    years=None,       # int or list of ints, e.g. 2024 or [2023, 2024]
    expand=True,      # auto-expand years when checking dates outside current range
    observed=True,    # include observed holidays (e.g. holiday on weekend → Monday)
    language=None,    # ISO 639-1 language code for holiday names, e.g. 'en', 'de'
    categories=None,  # filter to specific holiday categories (country-dependent)
)

Returns a HolidayBase object (dict-like: {date: name}).

Common Tasks

1. Get All Holidays for a Country in a Year

from holidays import country_holidays

us_holidays = country_holidays('US', years=2024)
for date, name in sorted(us_holidays.items()):
    print(date, name)

2. Get Holidays for a Subdivision (State / Province)

Use the ISO 3166-2 subdivision code (e.g. 'CA' for California, 'BY' for Bavaria).

from holidays import country_holidays

ca_holidays = country_holidays('US', subdiv='CA', years=2024)
for date, name in sorted(ca_holidays.items()):
    print(date, name)

3. Get Holidays Within a Date Range

Slice the HolidayBase object with date strings ('YYYY-MM-DD'):

from holidays import country_holidays

ca_holidays = country_holidays('US', subdiv='CA', years=2024)
for day in ca_holidays['2024-01-01':'2024-01-31']:
    print(f"{day}: {ca_holidays.get(day)}")

4. Check if a Specific Date is a Holiday

.get() returns the holiday name if the date is a holiday, or None if it is not.

from holidays import country_holidays

ca_holidays = country_holidays('US', subdiv='CA')

# Is December 25 a holiday?
name = ca_holidays.get('2024-12-25')
print(name)   # → 'Christmas Day'

# Is December 26 a holiday?
name = ca_holidays.get('2024-12-26')
print(name)   # → None

Tip: Use if date in holidays_obj: for a boolean check (faster than .get()).

5. Working with Custom Holidays

SECURITY NOTE: Only use custom holidays if the user explicitly provides or requests them. Never assume a file location exists.

ALWAYS ask the user for the file path rather than using a default location. If they don't have a custom holidays file, skip this feature.

Example workflow:

1. Ask user: "Do you have a custom holidays JSON file you'd like to include?"
2. If yes, ask: "What's the full path to your custom holidays file?"
3. Only then load and merge:

import json
from pathlib import Path
from holidays import country_holidays

# ONLY use this if user explicitly provided the path
custom_file = Path("/path/user/provided/custom-holidays.json")

# Verify file exists before reading
if custom_file.exists():
    with open(custom_file) as f:
        custom_data = json.load(f)

    holidays_2024 = country_holidays('US', years=2024)
    holidays_2024.update(custom_data)

    print(holidays_2024.get('2024-07-10'))  # → 'My Birthday!' (if defined)
else:
    print(f"File not found: {custom_file}")

Custom holidays file format:

{
  "2024-07-10": "My Birthday!",
  "2024-10-01": "Family Celebration"
}

6. List All Supported Countries and Subdivisions

from holidays import list_supported_countries

# include_aliases=True also returns common aliases (e.g. 'UK' for 'GB')
supported = list_supported_countries(include_aliases=True)
print(supported['US'])   # → list of supported US subdivision codes

7. Use Localized (Translated) Holiday Names

Language codes:

• Use ISO 639-1 codes (e.g., en, de, fr)
• Some countries use locale-specific codes (e.g., en_US, zh_CN)
• If an unsupported language is requested, the library falls back to the default language

Step 1: Find countries with localization support

from holidays import list_localized_countries

# Get all countries that support multiple languages
localized = list_localized_countries(include_aliases=True)

# Check if a specific country supports localization
if 'MY' in localized:
    print(f"Malaysia supports: {localized['MY']}")
    # Output: Malaysia supports: ['en_MY', 'ms_MY', 'zh_CN', ...]

Step 2: Generate holidays in a specific language

from holidays import country_holidays

# Malaysia holidays in Malay language
my_holidays_ms = country_holidays('MY', years=2025, language='ms_MY')
for date, name in sorted(my_holidays_ms.items())[:3]:
    print(f"{date}: {name}")

# Same holidays in English
my_holidays_en = country_holidays('MY', years=2025, language='en_MY')
for date, name in sorted(my_holidays_en.items())[:3]:
    print(f"{date}: {name}")

Key Behaviours to Know

• observed=True (default): When a holiday falls on a weekend, the observed date (typically Monday) is included. Set observed=False to get only the statutory date.
• expand=True (default): If you check a date outside the years range, the library automatically adds that year. Set expand=False to prevent this.
• Multiple years: Pass a list to years to load several years at once: years=[2023, 2024, 2025].
• Date keys: The HolidayBase dict accepts datetime.date, datetime.datetime, or 'YYYY-MM-DD' strings interchangeably as keys.
• Country codes: Use ISO 3166-1 alpha-2 (e.g. 'US', 'GB', 'DE'). Aliases like 'UK' are supported when include_aliases=True.

Dependencies

• Python: 3.10+
• Package: holidays (PyPI). Install with: pip install holidays --break-system-packages
• No external system dependencies required

Security Considerations

1. Package installation: Use --break-system-packages flag (required in this environment) and consider pinning to a specific version
2. Custom holidays files: Only load custom holidays when explicitly requested by the user with a user-provided path
3. File access: Verify file existence before reading to avoid exposing directory structure