✓ Verified 💻 Development ✓ Enhanced Data

Global Holidays

Use this skill whenever a task involves checking, generating, or working with public holidays — for

Rating: 4.4 (329 reviews)
Downloads: 3,770 downloads
Version: 1.0.0

Overview

Use this skill whenever a task involves checking, generating, or working with public holidays — for any country.

Complete Documentation

View Source →

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:

bash

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.

bash

pip install holidays --break-system-packages

For production use, pin to a specific version:

bash

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

Quick Reference

Task	Method
All holidays for a country/year	country_holidays('US', years=2024)
Holidays for a subdivision	country_holidays('US', subdiv='CA', years=2024)
Holidays in a date range	holidays_obj['2024-01-01':'2024-01-31']
Check if a date is a holiday	holidays_obj.get('2024-12-25') → name or None
Add custom holidays	holidays_obj.update({'2024-07-10': 'My Birthday!'})
List all supported countries	list_supported_countries()
List countries with localization	list_localized_countries()

Core API

`country_holidays()` — Main Function

python

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

python

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).

python

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'):

python

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.

python

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:

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

python

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:

json

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

6. List All Supported Countries and Subdivisions

python

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

python

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

python

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

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

Installation

Terminal bash


openclaw install global-holidays

Copied!

💻Code Examples

EOF

eof.txt

---

## Installation

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

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

pip-install-holidays058---break-system-packages.txt

---

## Quick Reference

| Task | Method |
|------|--------|
| All holidays for a country/year | `country_holidays('US', years=2024)` |
| Holidays for a subdivision | `country_holidays('US', subdiv='CA', years=2024)` |
| Holidays in a date range | `holidays_obj['2024-01-01':'2024-01-31']` |
| Check if a date is a holiday | `holidays_obj.get('2024-12-25')` → name or `None` |
| Add custom holidays | `holidays_obj.update({'2024-07-10': 'My Birthday!'})` |
| List all supported countries | `list_supported_countries()` |
| List countries with localization | `list_localized_countries()` |

---

## Core API

### `country_holidays()` — Main Function

)

.txt

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

---

## Common Tasks

### 1. Get All Holidays for a Country in a Year

print(date, name)

-printdate-name.txt

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

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

print(date, name)

-printdate-name.txt

### 3. Get Holidays Within a Date Range

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

print(f"{day}: {ca_holidays.get(day)}")

-printfday-caholidaysgetday.txt

### 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.

print(name) # → None

printname---none.txt

**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:

print(supported['US']) # → list of supported US subdivision codes

printsupportedus---list-of-supported-us-subdivision-codes.txt

### 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**

example.sh

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

example.py

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