holidays review
holidays 0.103 builds local Python mappings from dates to government holiday names for 250 country codes, with subdivisions, languages, and extra categories available only where each calendar implements them. It also has named financial-market calendars, though those contain holiday dates rather than trading sessions. Version 0.103 adds NZX and TWSE, changes the Holi 2026 date for NSE and BSE, and updates holidays in Gujarat and Maharashtra. Our Python 3.12 check imported it in 0.34 seconds and found packaged typing metadata.
Our holidays 0.103 install took 0.5 seconds, used 9 MB across 3 packages, imported in 0.34 seconds, and had no known audit findings. Use it for pinned, tested holiday lookups; use official rules for legal deadlines and a session calendar for trading hours.
We installed it
| Install | ✓ · 0.5s | 3 packages on disk · 9 MB |
| Import | ✓ | import holidays in 0.34s · pure Python · py.typed · requires Python >=3.10 |
| Known vulns | 0 | (pip-audit) |
Answers from our run
Does holidays install cleanly?
Yes. In a fresh container with an empty cache, pip install holidays finished in 0.5s, leaving 3 packages and 9 MB on disk. pip-audit reported no known vulnerabilities.
What does holidays need to run?
Python >=3.10, and nothing compiled: it is pure Python. In our run import holidays succeeded in 0.34s, and the package ships py.typed for type checkers.
holidays or workalendar: which should you use?
workalendar: Use it when its calendar classes and business-day methods cover your jurisdictions better. Our holidays 0.103 install took 0.5 seconds, used 9 MB across 3 packages, imported in 0.34 seconds, and had no known audit findings.
When should you not use holidays?
Payroll, tax, filing, or settlement output requires an official legal source; a community rules package cannot certify a deadline
Use it if
- A Python service needs public-holiday membership and names for a supported country and subdivision without calling a remote API
- Working-day arithmetic should use the same calendar object as date membership and observed-day handling
- The project support table explicitly lists the language and category your jurisdiction needs
- A financial-market holiday list is enough and you do not need opens, closes, breaks, or early sessions
- Payroll, tax, filing, or settlement output requires an official legal source; a community rules package cannot certify a deadline
- Production still runs Python 3.9 or older, because holidays 0.103 requires Python 3.10 or newer
- You assume every country has the same subdivision, translation, and BANK or SCHOOL category support; the README lists different coverage per calendar
- Reads must never mutate the calendar; expand defaults to true and a lookup can populate an unloaded year
- A trading engine needs session hours, breaks, early closes, or ad hoc closures; financial_holidays returns date-to-name mappings only
Setup reality
We installed holidays 0.103 in a fresh Python 3.12 Bookworm sandbox in 0.5 seconds. The environment ended with 3 packages occupying 9 MB. The distribution has one direct dependency, requires Python 3.10 or newer, and is pure Python. It ships py.typed, so type checkers can use its inline annotations. pip-audit reported zero known vulnerabilities, and import holidays completed in 0.34 seconds. Our package measurement could not identify a license from the installed metadata.
Construction choices determine the data you receive. Set the country, subdivision, years, observed policy, language, and categories explicitly. Country identifiers mainly follow ISO 3166-1, while subdivision aliases and extra categories vary by implementation. PUBLIC is the ordinary category. Passing BANK, SCHOOL, or another constant only makes sense when that country row documents it. Language fallback is also calendar-specific, so store codes rather than assuming one global default.
The default object can change during a read. With expand enabled, asking about a date in 2028 can calculate that year and append its holidays to an object initially built for 2027. Supply the full year range and use expand=False when stable iteration matters. observed defaults to true, and changing it later recalculates entries. Although strings and Unix timestamps are accepted, normalizing external input to datetime.date avoids ambiguous date strings at application boundaries.
Holiday rules are data, so an upgrade can change old output without breaking an import or method call. Version 0.103 corrected Holi in 2026 for two Indian exchanges and added two market calendars. Pin the package used for a generated schedule, record that version with exported results, and test dates that matter to the business. Financial calendars still need a session-calendar source when hours or early closes affect execution.
Patterns
Load one country and year load-country
import holidays
us = holidays.country_holidays('US', years=2026)
for day, name in sorted(us.items()):
print(day, name)Passing 2026 makes the initial mapping predictable; add expand=False if later reads must not insert another year.
Check a normalized calendar date check-date
from datetime import date
import holidays
calendar = holidays.country_holidays('US', years=2026)
day = date(2026, 7, 4)
name = calendar.get(day)
if name is not None:
print(name)HolidayBase accepts several input forms, but datetime.date avoids locale ambiguity at a service boundary.
Pick a documented subdivision choose-subdivision
import holidays
california = holidays.country_holidays(
'US', subdiv='CA', years=range(2026, 2029)
)US subdivision CA is explicit here; codes and aliases differ between country implementations.
Remove observed substitute days exclude-observed
import holidays
calendar = holidays.country_holidays(
'US', years=2026, observed=False
)observed defaults to true, and changing the property after creation can rebuild entries in the mapping.
Prevent lazy year expansion disable-expansion
import holidays
calendar = holidays.country_holidays(
'US', years=[2026, 2027], expand=False
)
assert calendar.get('2028-01-01') is NoneWith expand=False, the 2028 lookup stays absent instead of adding a third year during a read.
Request one supported language localize-names
import holidays
spain = holidays.country_holidays(
'ES', years=2026, language='es'
)The selected country controls supported_languages and fallback behavior; language availability is not global.
Combine implemented categories select-categories
from holidays import BANK, PUBLIC, country_holidays
belgium = country_holidays(
'BE', years=2026, categories=(PUBLIC, BANK), language='en_US'
)Belgium documents BANK alongside PUBLIC; validate categories against the chosen calendar before accepting configuration.
Test a working day check-working-day
import holidays
calendar = holidays.country_holidays('US', years=2026)
if calendar.is_working_day('2026-12-18'):
print('open')This result follows the calendar's weekend and holiday rules, which may differ from an employer's schedule.
Advance a deadline by workdays advance-working-days
import holidays
calendar = holidays.country_holidays('US', years=[2026, 2027])
due = calendar.get_nth_working_day('2026-12-18', 10)
print(due)Load 2026 and 2027 because a ten-day calculation near year end can cross into January.
Read a market holiday load-financial-market
import holidays
nyse = holidays.financial_holidays('NYSE', years=2026)
print(nyse.get('2026-12-25'))NYSE here returns dates and labels, not regular hours, breaks, or early closing times.
Search the displayed holiday name find-by-name
import holidays
calendar = holidays.country_holidays('US', years=2026, language='en_US')
dates = sorted(calendar.get_named('Thanksgiving'))
print(dates)Name matching depends on the chosen language and rule data; persist dates or business identifiers when wording can change.
Append an internal closure append-company-closure
from datetime import date
import holidays
calendar = holidays.country_holidays('US', years=2026)
calendar.append({date(2026, 12, 24): 'Company closure'})Keep company closures separately attributable even when the application combines them with public holidays.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| workalendar | PyPI | Use it when its calendar classes and business-day methods cover your jurisdictions better |
| pandas-market-calendars | PyPI | Use it for exchange schedules with opens, closes, breaks, and early sessions |
| business-calendar | PyPI | Use it for a small calendar assembled from your own workdays and closure dates |
More utils guides
lru-cache · ajv · type-fest · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.