---
id: jpholiday
version: "1.0.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# jpholiday — Pure-Python Japan Public Holiday Generate

License: permissive · Maintenance: active · Downloads: 679.6K/mo

## What it is and what it does

JPHoliday is a pure-Python library that provides access to Japanese national holidays based on official government data published by the Cabinet Office. It lets you check whether a specific date is a holiday, retrieve the holiday name, and query holidays across various time ranges—by specific date, year, month, or custom date range. The library handles substitute holidays (振替休日) automatically when a national holiday falls on a Sunday.

The package is designed for applications that need to respect Japanese business calendars, such as scheduling systems, payroll processing, or calendar applications. It supports both class-based and function-based APIs and allows you to register custom holidays via the OriginalHolidayCheckerInterface. Holiday data is verified through 2026 based on official announcements; queries beyond that year are possible but not guaranteed to be accurate.

Use it for:

- Check if a date is a Japanese national holiday when building scheduling or calendar applications.
- Generate lists of holidays for a given year or month to populate business calendars or time-off policies.
- Filter out Japanese holidays from work schedules or project timelines in payroll or project management systems.
- Query holidays within a date range to identify non-working days for compliance or reporting purposes.
- Register custom company holidays alongside national holidays for organization-specific calendar logic.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Queries Japanese national holidays and substitute holidays based on official government data, with methods to check if a date is a holiday, retrieve holiday names, and list holidays by date range, year, or month.

Yes. The package is lightweight, actively maintained, has no external dependencies, supports current Python versions, carries no known vulnerabilities, and solves a specific, well-defined problem for applications targeting Japanese calendars. Install it if you need reliable Japanese holiday lookups.

## Install

pip install jpholiday
uv add jpholiday
poetry add jpholiday

## Installing jpholiday

Before you install: Low friction install with no runtime dependencies. Actively maintained with recent commits and stable production status across Python 3.9 through 3.14.

License in practice: MIT license permits commercial and private use with minimal restrictions; you must include a copy of the license and copyright notice.

Quickstart:

pip install jpholiday

import jpholiday
import datetime

jpholiday.is_holiday(datetime.date(2017, 1, 1))
# True

jpholiday.is_holiday_name(datetime.date(2017, 1, 1))
# '元日'

Requires Python 3.9 or later. Holiday data is verified through 2026; accuracy beyond that year is not guaranteed.

Verify before relying:

- Whether the library updates its holiday data automatically or requires manual updates for years beyond 2026.
- Performance characteristics when querying large date ranges or years far in the future.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 679.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

japanese holiday calendar, japan public holidays, check if date is japanese holiday, japan national holidays library, japanese holiday lookup, japan holiday schedule, substitute holiday checker, japan-calendar, holiday-lookup

[View on SkillFed](https://skillfed.io/packages/jpholiday) · [View on PyPI](https://pypi.org/project/jpholiday/)