PyPIUtilsupdated 08 Aug 2026

holidays

Item: holidays
Rating: 4.8
Author: Keyoor

holidays is a Python framework and data library that generates public, bank, school, religious, unofficial, and other holiday calendars for countries, subdivisions, and selected financial markets. A calendar behaves like a dictionary keyed by date, so code can test membership, retrieve a localized holiday name, iterate a year, or calculate working days. Release 0.102 documents 250 country codes and a separate market catalog. Rules are implemented in Python and expanded for requested years, which is more flexible than shipping a static date file but makes version pinning important when legal rules change.

holidays · v0.102 · 7.2M/wk · ★ 1,916 · pushed 08 Aug 2026 · vacanza/holidays · docs · reviewed by Keyoor

Verdict

The practical default for broad country-holiday lookup in Python, as long as jurisdiction, subdivision, category, language, observed policy, and years are explicit. Treat its output as maintained reference data, not legal advice or a complete trading schedule.

API stability4/5The central HolidayBase mapping behavior, country_holidays and financial_holidays factories, years, subdiv, observed, expand, language, and categories parameters form a consistent interface across many releases. Version numbers are still 0.x, and calendar data changes are part of normal upgrades even when method signatures do not move. Applications that persist names or dates need fixture tests because data corrections can be behavior changes without an API break.

Docs5/5The Read the Docs site provides quick starts, a large support matrix for 250 country codes, explicit subdivision aliases, languages, category coverage, financial markets, working-day helpers, custom calendars, and ICS export examples. It explains observed and expand mutation with concrete output. The main difficulty is volume: users must consult the per-entity table rather than assume an option works consistently across every jurisdiction.

Maintenance5/5PyPI lists version 0.102, GitHub was pushed on 2026-08-08, and the README explains a disciplined dev-to-prerelease-to-stable flow. GitHub reports 82 open issues and pull requests, a reasonable active queue for a rules database spanning hundreds of jurisdictions. Calendar correctness depends on continuous legal updates, and the visible same-day activity plus regular version progression is exactly what this kind of package needs.

Ecosystem5/5The project covers 250 country codes plus selected financial markets, offers localized names and optional categories where implemented, and exposes ordinary dict-like data that works with standard Python. The docs also point to ICS export tooling. Breadth is excellent, but it should not be confused with uniform depth: country entries advertise their own subdivision, language, and category support, and trading-session users still need a market-specific library.

Use it if

You need country and state or province holiday dates as Python date keys without maintaining rule tables yourself
You want dict-like membership checks plus working-day helpers in one object
You need supported localized holiday names or non-public categories for a documented jurisdiction
You need one interface for national calendars and selected exchanges such as NYSE

Skip it if

You need a legal or payroll guarantee: the project is community-maintained data and its README asks contributors to supply corrections, not a compliance service
Your runtime is Python 3.9 or older: release 0.102 requires Python 3.10 or newer
You assume every country has equal depth: the README's table shows subdivisions, languages, and extra categories vary by entity
You need immutable calendar contents: expand and observed are mutable, and the docs show that querying a new year can add dates to the object
You only need exchange sessions, early closes, and trading minutes: financial_holidays returns holiday dates, while dedicated market-calendar packages model sessions in more detail

Setup reality

Install holidays 0.102 on Python 3.10 or newer; its only declared runtime dependency is python-dateutil 2.9 or later and below 3. The hard part is choosing the exact calendar contract. Prefer country_holidays('US', subdiv='CA', years=2026) over a broad US() with defaults hidden in another module. Country codes generally follow ISO 3166-1, subdivisions follow ISO 3166-2, and market identifiers generally use MIC codes, but aliases exist and the support table is the authority. Public holidays are the default category. Bank, school, religious, unofficial, and other categories exist only for calendars that list them, so do not pass a category merely because another country supports it. observed defaults to True, meaning substitute dates can appear alongside the named holiday. expand also defaults to True: asking whether a date from a year not loaded can calculate that year and mutate the dictionary. Set explicit years and expand=False when deterministic size and iteration matter. Language selection has country-specific support and fallback behavior; pin language if names are stored, compared, exported, or shown to users. Membership accepts dates, strings, and Unix timestamps, which is convenient but permissive. Normalize external input to datetime.date if ambiguous locale date strings would be risky. Holiday laws change, corrections can alter past dates, and the dev branch publishes timestamped pre-releases before stable releases. Pin the stable version, record it with generated schedules, and regression-test the exact jurisdictions and years your business uses. For payroll, settlement, or statutory deadlines, add an authoritative review process rather than treating a successful import as legal verification.

Patterns

Create an explicit country calendarload-country-calendar

import holidays

us_2026 = holidays.country_holidays('US', years=2026)
for day, name in sorted(us_2026.items()):
    print(day, name)

Pass years explicitly. With the default expand=True, later lookups in other years can add entries to the object.

Check a date and retrieve its namecheck-holiday

from datetime import date
import holidays

calendar = holidays.country_holidays('US', years=2026)
day = date(2026, 7, 4)
if day in calendar:
    print(calendar.get(day))

Membership also accepts strings and Unix timestamps, but datetime.date avoids ambiguous external date formats.

Load holidays for a subdivisionselect-subdivision

import holidays

california = holidays.country_holidays(
    'US', subdiv='CA', years=range(2026, 2029)
)

Subdivision support and aliases vary by country. Use the code listed for that entity instead of guessing from a place name.

Exclude substitute observed datesdisable-observed-days

import holidays

statutory_dates = holidays.country_holidays(
    'US', years=2026, observed=False
)

observed defaults to True. The flag can also be changed after construction, which recalculates the calendar contents.

Prevent lookups from adding yearsfreeze-year-expansion

import holidays

calendar = holidays.country_holidays('US', years=[2025, 2026])
calendar.expand = False
assert len(calendar) == len(list(calendar.items()))

With expand=True, checking an unloaded year populates it. Disable expansion when iteration and memory use must stay deterministic.

Request supported localized namesset-language

import holidays

spanish_names = holidays.country_holidays(
    'ES', years=2026, language='es'
)

Languages differ by calendar and have fallback rules. Check supported_languages before depending on a particular locale.

Combine supported holiday categoriesselect-categories

from holidays import BANK, PUBLIC, country_holidays

belgium = country_holidays(
    'BE', years=2026, categories=(BANK, PUBLIC), language='en_US'
)

PUBLIC is the default. Other category constants only work for entities that list them in supported_categories.

Check and advance through working dayscalculate-working-day

import holidays

us = holidays.US(years=[2026, 2027])
if us.is_working_day('2026-12-18'):
    due = us.get_nth_working_day('2026-12-18', 5)
    print(due)

Working-day helpers account for that calendar's weekend and holiday rules. Load every year the calculation may cross.

Load financial-market holidaysload-market-calendar

import holidays

nyse = holidays.financial_holidays('NYSE', years=2026)
print(nyse.get('2026-12-25'))

This returns holiday dates and names, not a complete session schedule with opens, closes, breaks, and trading minutes.

Find dates by partial holiday namesearch-by-name

import holidays

us = holidays.UnitedStates(years=2026)
matches = sorted(us.get_named('thanksgiving'))
print(matches)

Name matching depends on the calendar language. Pin language before storing or comparing name-based results.

Extend a calendar with company closuresadd-custom-date

from datetime import date
import holidays

calendar = holidays.country_holidays('US', years=2026)
calendar.append({date(2026, 12, 24): 'Company closure'})

The custom entry lives only in this object. Keep company policy separate if you need to distinguish statutory holidays from internal closures.

Alternatives

Package	Registry	Pick it when
workalendar	PyPI	You want workday arithmetic and calendars with an object model centered on business-day operations
pandas-market-calendars	PyPI	You need exchange schedules, opens, closes, and early-closing sessions in pandas
exchange-calendars	PyPI	You need detailed trading sessions and minute-level exchange calendar operations