# holidays

> Open World Holidays Framework

- **URL**: https://www.freshcrate.ai/projects/holidays
- **Author**: Vacanza Team
- **Category**: Frameworks
- **Latest version**: `v0.98` (2026-06-01)
- **License**: Unknown
- **Source**: https://github.com/vacanza/holidays/releases/
- **Homepage**: https://pypi.org/project/holidays/
- **Language**: Python
- **GitHub**: 1,878 stars, 685 forks
- **Registry**: pypi (`holidays`)
- **Tags**: `calendar`, `holidays`, `l10n`, `pypi`, `vacation`, `worldwide`

## Description

# Holidays

A fast, efficient Python library for generating country- and subdivision- (e.g. state or province)
specific sets of government-designated holidays on the fly. It aims to make determining whether a
specific date is a holiday as fast and flexible as possible.

<!-- markdownlint-disable MD033 -->
<table>
  <tr>
    <td>PyPI</td>
    <td>
      <a href="https://pypi.org/project/holidays"><img src="https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fvacanza%2Faux%2Frefs%2Fheads%2Fmain%2Fbadges%2Fdownloads%2Fpepy.tech.yaml&query=%24.previous_month_downloads_human&suffix=%2Fmonth&style=flat&label=downloads&color=41B5BE&cacheSeconds=86400" alt="PyPI monthly downloads"></a>&nbsp;<a href="https://pypi.org/project/holidays"><img src="https://img.shields.io/pypi/v/holidays?color=41B5BE&label=version&style=flat" alt="PyPI version"></a>&nbsp;<a href="https://github.com/vacanza/holidays/releases"><img src="https://img.shields.io/github/release-date/vacanza/holidays?color=41B5BE&style=flat" alt="Latest release date"></a>
    </td>
  </tr>
  <tr>
    <td>CI/CD</td>
    <td>
      <a href="https://github.com/vacanza/holidays/actions/workflows/ci-cd.yml?query=branch%3Adev"><img src="https://img.shields.io/github/actions/workflow/status/vacanza/holidays/ci-cd.yml?branch=dev&color=41B5BE&style=flat" alt="CI/CD status"></a>&nbsp;<a href="https://holidays.readthedocs.io/en/latest/?badge=latest"><img src="https://img.shields.io/readthedocs/holidays?color=41B5BE&style=flat&label=documentation" alt="Documentation build status"></a>&nbsp;<a href="https://security.snyk.io/package/pip/holidays/"><img alt="Open World Holidays Package Health Score" src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fsecurity.snyk.io%2Fpackage%2Fpip%2Fholidays%2F&search=(class%3D%22score-number%22.*%3F%3E)(%5Cd%7B1%2C3%7D%2F%5Cd%7B1%2C3%7D)&replace=%242&style=flat&label=snyk&color=41B5BE"></a>
    </td>
  </tr>
  <tr>
    <td>Code</td>
    <td>
      <a href="https://github.com/vacanza/holidays/blob/dev/LICENSE"><img src="https://img.shields.io/github/license/vacanza/holidays?color=41B5BE&style=flat" alt="License"></a>&nbsp;<a href="https://pypi.org/project/holidays"><img src="https://img.shields.io/pypi/pyversions/holidays?label=python&color=41B5BE&style=flat" alt="Python supported versions"></a>&nbsp;<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/style-ruff-41B5BE?style=flat" alt="Code style"></a>&nbsp;<a href="https://app.codecov.io/gh/vacanza/holidays"><img src="https://img.shields.io/codecov/c/github/vacanza/holidays/dev?color=41B5BE&style=flat" alt="Code coverage"></a>
    </td>
  </tr>
  <tr>
    <td>Docs</td>
    <td>
      <a href="https://holidays.readthedocs.io/en/latest/"><img src="https://img.shields.io/badge/documentation-readthedocs.io-41B5BE?style=flat" alt="Documentation on Read the Docs"></a>&nbsp;<a href="https://deepwiki.com/vacanza/holidays"><img src="https://img.shields.io/badge/documentation-deepwiki.com-41B5BE?style=flat" alt="Documentation on DeepWiki"></a>
    </td>
  </tr>
  <tr>
    <td>GitHub</td>
    <td>
      <a href="https://github.com/vacanza/holidays/stargazers"><img src="https://img.shields.io/github/stars/vacanza/holidays?color=41B5BE&style=flat" alt="GitHub stars"></a>&nbsp;<a href="https://github.com/vacanza/holidays/forks"><img src="https://img.shields.io/github/forks/vacanza/holidays?color=41B5BE&style=flat" alt="GitHub forks"></a>&nbsp;<a href="https://github.com/vacanza/holidays/graphs/contributors"><img src="https://img.shields.io/github/contributors/vacanza/holidays?color=41B5BE&style=flat" alt="GitHub contributors"></a>&nbsp;<a href="https://github.com/vacanza/holidays/commits/dev"><img src="https://img.shields.io/github/last-commit/vacanza/holidays/dev?color=41B5BE&style=flat" alt="GitHub last commit"></a>
    </td>
  </tr>
  <tr>
    <td>Citation</td>
    <td>
      <a href="https://doi.org/10.5281/zenodo.14884702"><img src="https://img.shields.io/badge/DOI-10.5281/zenodo.14884702-41B5BE?style=flat" alt="Open World Holidays Framework DOI"></a>
    </td>
  </tr>
</table>

## Install

The latest stable version can always be installed or updated via pip:

``` shell
pip install --upgrade holidays
```

The latest development (dev) version can be installed directly from GitHub:

``` shell
pip install --upgrade https://github.com/vacanza/holidays/tarball/dev
```

All new features are always first pushed to dev branch, then released on main branch upon official
version upgrades.

## Documentation

The documentation is hosted on [Read the Docs](https://holidays.readthedocs.io).

## ICS Exports

Holiday calendars can be exported as `.ics` files via the [download page](https://holidays.readthedocs.io/en/latest/downloads/).

## Quick Start

``` python
from datetime import date
import holidays

us_holidays = holidays.US()  # this is a dict-like object
# the below is the same, but takes a string:
us_holidays = holidays.countr

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v0.98` | 2026-06-01 | High | ## Version 0.98  Released June 1, 2026  - Add NASDAQ (XNAS) holidays (#3586 by @pareshjoshij) - Update United Arab Emirates holidays: fix Thai localization (#3596 by @KJhellico) - Update Bhutan holidays (#3590 by @KJhellico) - Update l10n test: check .po files for missing entries comments (#3594 by @KJhellico) - Add 2025-2026 Islamic holidays exact dates for Indonesia and Philippines (#3591 by @akshiDhi) - Add Tibetan calendar generator (#3330 by @Abiram08, @KJhellico) - Add pre-commit |
| `v0.97` | 2026-05-18 | High | ## Version 0.97  Released May 18, 2026  - Refactor calendar generators (#3565 by @KJhellico) - Update Bangladesh holidays: add Islamic holidays (#3531 by @shaonahamed0, @KJhellico, @PPsyrius) - Update CI/CD workflows: set default Python and uv versions (#3581 by @KJhellico) - Update China holidays: update official reference links (#3569 by @nuomi1) - Update European Central Bank holidays: correct historical closures for 1999-2001 (#3572 by @pareshjoshij) - Update India holidays: add Mah |
| `v0.96` | 2026-05-04 | High | ## Version 0.96  Released May 4, 2026  - Add static type checking support for `countries` and `financial` aliases (#3549 by @PPsyrius, @arkid15r) - Refactor India holidays testcases (#3524 by @PPsyrius, @arkid15r) - Update .po files generator: use git user identity for "Last-Translator" field (#3553 by @KJhellico) - Update Arabic localization: fix "estimated" and "observed" labels translation (#3551 by @dimssu) - Update Brazil holidays (#3558 by @KJhellico) - Update Germany holidays: ad |
| `0.95` | 2026-04-21 | Low | Imported from PyPI (0.95) |
| `v0.95` | 2026-04-20 | High | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |
| `v0.95` | 2026-04-20 | High | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |
| `v0.95` | 2026-04-20 | High | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |
| `v0.95` | 2026-04-20 | High | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |
| `v0.95` | 2026-04-20 | High | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |
| `v0.95` | 2026-04-20 | Medium | ## Version 0.95  Released April 20, 2026  - Refactor PO generator for robust metadata and improved class discovery (#3204 by @pareshjoshij, @arkid15r, @KJhellico, @PPsyrius) - Refactor conditional logic using structural pattern matching (PEP 636) (#3518 by @PPsyrius) - Fix typography: replace U+2019 with "'" and U+2013 with '-' (#3539 by @KJhellico) - Update .pre-commit-config.yaml: use SHA for versions (#3516 by @arkid15r) - Update Austria holidays (#3513 by @PPsyrius, @arkid15r) - Upd |

## Citation

- HTML: https://www.freshcrate.ai/projects/holidays
- Markdown: https://www.freshcrate.ai/projects/holidays.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/holidays/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._