{"id":875,"library":"holidays","title":"Holidays","description":"The Python `holidays` library (currently v0.93) is an Open World Holidays Framework that provides a fast and efficient way to determine if a specific date is a public holiday in various countries and subdivisions. It is actively maintained with frequent, approximately bi-weekly, releases adding new countries, regions, and localization support. It is commonly used in scheduling, automation systems, and applications requiring holiday awareness.","status":"active","version":"0.93","language":"python","source_language":"en","source_url":"https://github.com/vacanza/holidays/","tags":["holidays","dates","calendar","localization","time"],"install":[{"cmd":"pip install holidays","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary module import to access country-specific holiday classes or the generic HolidayBase.","symbol":"holidays","correct":"import holidays"},{"note":"To get holidays for a specific country, instantiate its class directly, optionally passing years and other parameters.","symbol":"UnitedStates","correct":"import holidays\nus_holidays = holidays.UnitedStates(years=[2026])"}],"quickstart":{"code":"from datetime import date\nimport holidays\n\n# Get all US federal holidays for a specific year\nus_holidays_2026 = holidays.UnitedStates(years=[2026])\n\nprint(f\"Is New Year's Day (Jan 1, 2026) a holiday? {date(2026, 1, 1) in us_holidays_2026}\")\nprint(f\"Holiday name for Jan 1, 2026: {us_holidays_2026.get(date(2026, 1, 1))}\")\n\n# Get California state holidays for a year\nca_holidays_2026 = holidays.UnitedStates(years=[2026], state='CA')\n\n# Check a specific date (e.g., California's observed Juneteenth, if applicable)\nexample_date = date(2026, 6, 19) # Juneteenth National Independence Day\nprint(f\"Is {example_date} a holiday in California? {example_date in ca_holidays_2026}\")\nif example_date in ca_holidays_2026:\n    print(f\"Holiday name: {ca_holidays_2026.get(example_date)}\")\n\n# Get holidays in German for Germany\nde_holidays_2026_de = holidays.Germany(years=[2026], language='de')\nprint(f\"German holiday name for Jan 1, 2026: {de_holidays_2026_de.get(date(2026, 1, 1))}\")","lang":"python","description":"This quickstart demonstrates how to instantiate the holidays object for a specific country (United States) and subdivision (California), check if a date is a holiday, and retrieve its name. It also shows how to get holiday names in a specific language (German for Germany)."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer, or pin the `holidays` dependency to `<0.84` if Python 3.9 is required.","message":"Python 3.9 support was officially dropped in version 0.84 of the library.","severity":"breaking","affected_versions":">=0.84"},{"fix":"Always specify the `state` or `prov` parameter (e.g., `holidays.UnitedStates(state='CA')`) when you need subdivision-specific holidays.","message":"When querying holidays for countries with subdivisions (states, provinces), not specifying the `state` or `prov` parameter will only return national holidays, potentially missing relevant regional holidays. For example, `holidays.UnitedStates()` will not include state-specific holidays like California's Diwali.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To disable observed holidays, initialize the country object with `observed=False` (e.g., `holidays.UnitedStates(observed=False)`).","message":"The library includes 'observed' holidays (e.g., when a holiday falls on a weekend, the preceding or following weekday is observed) by default (`observed=True`). This might not be desired if only the official fixed date is needed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It is highly recommended to pin your `holidays` dependency to avoid unexpected upgrades to version 1.0 or later that might contain breaking changes. For example, use `holidays<1.0` or `holidays==0.93`.","message":"The project plans to adopt a loose form of Semantic Versioning (SemVer) starting from version 1.0. This means future major versions (1.x.x) may introduce backward-incompatible API changes. While not yet a breaking change, it's a strong advisory.","severity":"deprecated","affected_versions":"All v0.x versions"},{"fix":"Specify the `language` parameter during instantiation to get holiday names in a desired locale (e.g., `holidays.Germany(language='de')`). Consult the documentation for supported languages per country.","message":"Holiday names are returned in a default language (often English or the country's primary language) unless explicitly specified. This can lead to unexpected language output if localization is important.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':38 'ad':47 'applic':63 'approxim':42 'autom':60 'awar':66 'bi':44 'bi-week':43 'calendar':69 'common':56 'countri':33,49 'current':6 'date':26,68 'determin':22 'effici':19 'fast':17 'framework':13 'frequent':41 'holiday':1,4,12,30,65,67 'librari':5 'local':52,70 'maintain':39 'new':48 'open':10 'provid':15 'public':29 'python':3 'region':50 'releas':46 'requir':64 'schedul':59 'specif':25 'subdivis':35 'support':53 'system':61 'time':71 'use':57 'v0.93':7 'various':32 'way':20 'week':45 'world':11","created_at":"2026-03-29T06:05:46.552203+00:00","updated_at":"2026-04-16T15:35:16.907905+00:00","problems":[{"fix":"Ensure the library is installed in your current environment by running: `pip install holidays`","cause":"The `holidays` library is not installed in the active Python environment, or the environment where it's installed is not being used.","error":"ModuleNotFoundError: No module named 'holidays'"},{"fix":"Explicitly tell PyInstaller to include the necessary submodules using hidden imports, e.g.: `pyinstaller your_script.py --hidden-import holidays.countries --hidden-import holidays.financial` (add more as needed)","cause":"When building an executable with PyInstaller, it may fail to automatically detect and include all dynamically imported country submodules of the `holidays` library.","error":"ModuleNotFoundError: No module named 'holidays.countries'"},{"fix":"Use the `holidays.country_holidays()` factory function or `getattr()` for dynamic country access: `country_code = 'US'; us_holidays = holidays.country_holidays(country_code)` or `us_holidays = getattr(holidays, country_code)()`","cause":"You are trying to access a country-specific holiday class (e.g., `holidays.US`) dynamically using a string variable directly as an attribute, which Python does not support this way.","error":"AttributeError: module 'holidays' has no attribute 'i' (or similar like 'US' when using a variable)"},{"fix":"Initialize a specific country's holidays, for example: `us_holidays = holidays.US()` or `us_holidays = holidays.country_holidays('US')`","cause":"The `holidays` module itself is being called as a function (e.g., `holidays()`) instead of initializing a specific country's holiday object or using a factory function.","error":"TypeError: 'module' object is not callable"},{"fix":"Check the official documentation or `holidays.list_supported_countries()` for available countries and subdivisions; consider contributing the missing data or upgrading the library.","cause":"The requested country or subdivision's holiday data is not yet implemented or supported by the installed `holidays` library version.","error":"NotImplementedError"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.103","cli_name":"","cli_version":null,"type":"library","homepage":"https://python-holidays.readthedocs.io","github":"https://github.com/vacanza/holidays","docs":"https://holidays.readthedocs.io/en/latest/","changelog":"https://github.com/vacanza/holidays/releases/","pypi":"https://pypi.org/project/holidays/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","devops","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}