Python Holidays: Installation and Country Calendars

What `holidays` solves for Python applications

`holidays` is a Python library for generating government-designated holiday sets by country and, where applicable, subdivision. Its target users include developers building applications that need to identify public holidays, calculate working-day differences, populate scheduling interfaces, or attach holiday names to dates. The package classifiers also name education, finance, insurance, desktop use, scheduling, and accounting among its intended areas.

The library distinguishes country calendars from financial calendars. A country calendar such as `holidays.US()` represents government-designated holidays, while `holidays.NYSE()` selects the New York Stock Exchange calendar. That distinction matters because an exchange closure schedule is not interchangeable with every federal, state, or local holiday. The financial API follows the same general dict-like access model as the country API.

Coverage is broad rather than universal. The README states that the library supports 250 country codes, primarily based on ISO 3166-1, plus a small number of user-assigned or reserved codes such as `XK` for Kosovo. Subdivisions use ISO 3166-2 codes. This makes selection scriptable, but it also means an application should validate its country and subdivision code instead of accepting arbitrary user input without checking the documented calendar definitions.

The project is intended for Python 3.10 and later. Its only declared runtime dependency is `python-dateutil>=2.9.0.post0,<3`. It is classified as beta, which is a useful adoption signal rather than a guarantee about the suitability of every individual calendar.

How date lookup works in `holidays`

The central abstraction is `HolidayBase`, a dict-like class returned by country and financial calendar constructors. An application can instantiate a calendar, test whether a date belongs to it, and retrieve the holiday name by a date key. This keeps calendar use close to ordinary Python collection behavior without requiring a separate service.

The documented lookup mechanism accepts multiple date representations. A `datetime.date`, an ISO-style string such as `"2014-01-01"`, a US-style string such as `"1/1/2014"`, and a Unix timestamp are all recognized by `HolidayBase`. That flexibility helps when dates arrive from configuration files, JSON payloads, forms, or database records. It does not make every input format safe without validation. In particular, accepting `"1/1/2014"` does not establish that every country should interpret that string in the same way, so applications should normalize inputs at their boundaries when ambiguity matters.

Subdivisions are represented by additional calendar objects. The README demonstrates selecting Puerto Rico with `subdiv="PR"`. A date absent from the general US calendar can therefore be present in a subdivision-specific calendar. The data flow is straightforward: choose a country code, optionally choose a subdivision, instantiate the calendar, then query it with a date-like key.

For calendar export, `pyproject.toml` registers the `holidays-ics` command through `holidays.generate_ics:main`. The README also points to downloadable holiday calendars and an ICS export example in the documentation. The repository includes `snapshots/`, `scripts/`, and `tests/`, indicating that calendar definitions, generated assets, and verification are organized as separate parts of the project. The exact internal rules for every jurisdiction are not reproduced in the README, so applications requiring auditable legal or policy explanations should inspect the relevant calendar implementation and documentation.

Installing `holidays` and checking the first date

The README says to install or update the latest stable release with `pip`. This is the documented starting point for an application that should receive official PyPI releases rather than development builds.

pip install --upgrade holidays

The command installs the package named `holidays` into the active Python environment. The README does not prescribe a virtual environment command, so the environment setup must be handled by the surrounding project.

A first country lookup can follow the documented quick-start form. The following example constructs a US calendar and checks two dates. The expected results shown in the README are `True` for New Year's Day in 2015 and `False` for January 2, 2015.

from datetime import date
import holidays

us_holidays = holidays.US()

date(2015, 1, 1) in us_holidays
date(2015, 1, 2) in us_holidays
us_holidays.get("2014-01-01")

The `get()` call returns the named holiday `"New Year's Day"` for the documented date. An application can use the same pattern with `holidays.country_holidays("US")`, which the README describes as equivalent to the constructor form.

If a country calendar includes holidays that vary by region, pass the subdivision code through the documented keyword. The library supports subdivision-aware calendars, including Puerto Rico.

us_holidays = holidays.country_holidays("US")
us_pr_holidays = holidays.country_holidays("US", subdiv="PR")

"2018-01-06" in us_holidays
"2018-01-06" in us_pr_holidays

The README shows the first membership check returning `False` and the second returning `True`.

Country, subdivision, and financial calendar selection

Calendar selection is the main design decision for a new user. Country names are not the primary identifiers. The README directs users toward ISO 3166-1 alpha-2 codes such as `US`, with subdivision identifiers based on ISO 3166-2. This keeps code-based configuration compact and aligns country selection with established geographic codes. It also means that aliases, common names, and abbreviations may be present, but the README excerpt does not document the complete alias set, so it should not be treated as a complete input contract.

Subdivisions are useful when a national result is too broad. The Puerto Rico example shows a real difference in the resulting membership set. That same pattern can be applied wherever the library provides a subdivision rule, but the existence of a subdivision code does not by itself guarantee that every holiday varies there. An application should document which subdivision policy it has chosen when a result can differ by state, province, territory, or other local scope.

Financial calendars are a separate selection path. `holidays.NYSE()` and `holidays.financial_holidays("NYSE")` return dict-like objects according to the README. This is the appropriate distinction for code that models exchange closures, but the library does not claim that an exchange calendar represents every commercial organization. A company may observe different holidays, have its own weekends, or apply closure rules that are absent from a public calendar.

The package therefore solves calendar lookup at a selected geographic or institutional scope. It does not remove the need to identify that scope in the consuming application. In services with multiple tenants, the country, subdivision, and calendar class should be configuration rather than hard-coded assumptions.

Limits of government holiday data

The clearest limitation is the project's stated subject: government-designated holidays. It should not be treated as a complete observance, vacation, or business-continuity database. The README does not claim to cover company anniversaries, employee leave, school vacations, local municipal closures, religious days that are not official public holidays, or exchange-specific rules beyond the financial calendars supplied.

Date membership also hides an important policy decision. A calendar can return `True` for a holiday while the consuming organization remains open. Conversely, an organization can close on a day that is not in the selected government or exchange calendar. This is why holiday-aware payroll, billing, staffing, and delivery software should document whether a date is being used as a public holiday, a financial-market closure, or an organization-specific non-working day.

Subdivision support increases precision only when the right code is selected. Passing an unsupported or unintended subdivision may either produce a narrower calendar or fail depending on the library's validation behavior, which the README excerpt does not fully specify. The documentation does not provide a universal rollback or data-correction workflow for a particular date, so applications should not silently treat the package as an authoritative source for regulated scheduling without a review process.

The library also has a version boundary. Python 3.10 is the minimum supported version, and the package is marked beta in `pyproject.toml`. These are ordinary adoption constraints rather than defects, but they belong in dependency policy for production services.

Release activity, licensing, and upgrade work

Maintenance signals are recent. The repository is not archived, and the last push was on 2026-10-15. Recent releases include v0.106 on 2026-10-05, v0.105 on 2026-09-21, and v0.104 on 2026-09-07. This supports a current release cadence, but it does not guarantee that every calendar change is compatible with an application's existing business logic. Holiday definitions can change, and a package update may therefore alter date membership rather than only the library's implementation.

The README describes the development flow: new features are first pushed to the `dev` branch and published as PyPI pre-releases, then released from `main` on official version upgrades. Production installations should normally use the stable command shown earlier. Developers who need the latest pre-release can use the separately documented command.

pip install --upgrade --pre holidays

That command is appropriate only when the application is prepared to receive pre-release behavior. The repository's `VERSION` file identifies the upcoming stable version, while pre-release package names append a UTC timestamp in the `.devYYYYMMDDHHMMSS` form.

The project is licensed under MIT. `pyproject.toml` names the license and lists `LICENSE` and `CONTRIBUTORS` as license files. That is a permissive license, but users still need to review the repository license text and their own distribution obligations. Upgrade work is mostly dependency management plus regression checks around representative country, subdivision, financial, and historical dates. The project includes tests, snapshots, changelog material, and documentation, but the repository does not quantify upgrade effort.

Editorial conclusion

Adopt `holidays` when an application needs Python-native calendars based on ISO country or subdivision codes and can accept the library's government-designated holiday model. Do not use it as the sole source for company closures, school breaks, religious observances, or jurisdiction-specific schedules. Before adoption, verify the required Python version, inspect the documented calendars and subdivision codes, and compare representative dates against the rules that govern the target organization. The package supports Python 3.10 and newer, uses the MIT license, and had its last push on 2026-10-15.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vacanza/holidays on GitHub