jpholiday

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 on this page — 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

jpholiday on PyPI

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

Evidence: jpholiday-1.0.3-py3-none-any.whl

Keywords: japan, holiday, japanese, calendar, public-holiday, 祝日

Tags

More Python Modules packages