{"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,"last_verified":"2026-05-12T20:40:59.278Z","next_check":"2026-06-27T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.96","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"0.83","pypi_latest":"0.96","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.29,"mem_mb":6.7,"disk_size":"29.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":6.7,"disk_size":"28.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.1,"import_time_s":0.17,"mem_mb":6.7,"disk_size":"29M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":6.7,"disk_size":"29M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.98,"mem_mb":7.3,"disk_size":"32.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.96,"mem_mb":7.2,"disk_size":"31.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.2,"import_time_s":0.79,"mem_mb":7.3,"disk_size":"33M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":7.2,"disk_size":"32M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.72,"mem_mb":7.8,"disk_size":"23.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.75,"mem_mb":7.8,"disk_size":"23.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.1,"import_time_s":0.76,"mem_mb":7.8,"disk_size":"24M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":7.8,"disk_size":"24M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.7,"mem_mb":7.9,"disk_size":"23.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":7.9,"disk_size":"22.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.1,"import_time_s":0.76,"mem_mb":7.9,"disk_size":"24M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":7.9,"disk_size":"23M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.11,"mem_mb":4.3,"disk_size":"27.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":4.3,"disk_size":"27.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.4,"import_time_s":0.08,"mem_mb":4.3,"disk_size":"28M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"holidays","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":4.3,"disk_size":"28M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}