Registry / serialization / jpholiday

jpholiday

JSON →
library1.0.3pypypi✓ verified 92d ago

jpholiday is a pure-Python library designed to easily retrieve Japan's national holidays based on data published by the Cabinet Office. It is currently at version 1.0.3 and maintains an active release cadence with several updates in recent months, continuously improving accuracy and functionality.

pip install jpholiday
INSTALL
IMPORT
SIG · JPHOLIDAY
J
jpholiday
serializationpythonv1.0.3
Install
1.5s avg
Import
55ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.058s · 18MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.052s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

JPHoliday
✓ from jpholiday import JPHoliday

This quickstart demonstrates how to check if a specific date is a holiday, retrieve holiday names for a given date, and list all holidays for a particular year using the JPHoliday class.

import datetime from jpholiday import JPHoliday # Initialize the JPHoliday instance jpholiday_instance = JPHoliday() # Check if a specific date is a holiday date_to_check = datetime.date(2024, 1, 1) # New Year's Day is_holiday = jpholiday_instance.is_holiday(date_to_check) print(f"Is {date_to_check} a holiday? {is_holiday}") # Get the name(s) of holidays on a specific date holidays_on_date = jpholiday_instance.holidays(date_to_check) if holidays_on_date: for holiday in holidays_on_date: print(f"Holiday on {holiday.date}: {holiday.name}") # Get all holidays for a specific year year_to_check = 2024 year_holidays = jpholiday_instance.year_holidays(year_to_check) print(f"\nHolidays in {year_to_check} (first 3):") for holiday in year_holidays[:3]: print(f" {holiday.date}: {holiday.name}")
Debug
Known issues
breakingThe interface for defining custom holidays (`OriginalHoliday`) changed significantly in v1.0.0, causing incompatibility with previous versions. Custom holiday implementations require updates.
fix
Review and rewrite custom holiday classes to align with the new `OriginalHoliday` interface introduced in v1.0.0 and later.
affects: <1.0.0
gotchaVersions prior to v1.0.1 had issues with correct imports, which could lead to `ImportError` or unexpected behavior.
fix
Upgrade to v1.0.1 or newer to resolve import stability issues. Ensure your import statement is `from jpholiday import JPHoliday`.
affects: <1.0.1
deprecatedSupport for Python 3.5 was officially removed in version 0.1.6.
fix
Ensure your project uses Python 3.9 or newer, as specified in the `requires_python` metadata.
affects: <0.1.6
gotchaAccuracy for holidays beyond 2027 is not guaranteed. While the library can calculate them, official announcements from the Cabinet Office are only verified up to 2027.
fix
Be aware that holiday data for years past 2027 may be provisional and subject to change upon official government announcement. Use with caution for long-term planning.
affects: All versions (for future dates)
gotchaOlder versions (prior to v0.1.5) had discrepancies with Cabinet Office data for certain days between 1990 and 2021 (specifically, 4 days were incorrect).
fix
Upgrade to v0.1.5 or newer to ensure the most accurate historical holiday data is used, correcting previous discrepancies.
affects: <0.1.5
Errors
Common errors & fixes
AttributeError: 'Series' object has no attribute 'month'
The `jpholiday` functions like `is_holiday` expect a single `datetime.date` or `datetime.datetime` object, but are being applied directly to a Pandas Series, which is a collection of dates, not a single date object.
fix
Use the `.map()` or `.apply()` method on the Pandas Series to apply the `jpholiday` function to each individual date within the Series.
```python
import jpholiday
import pandas as pd
import datetime

dates_series = pd.Series([datetime.date(2023, 1, 1), datetime.date(2023, 1, 2), datetime.date(2023, 1, 3)])
is_holiday_series = dates_series.map(jpholiday.is_holiday)
print(is_holiday_series)
```
AttributeError: 'OriginalHoliday' object has no attribute 'original_holidays'
This error typically occurs when attempting to implement a custom holiday checker by inheriting from `jpholiday.OriginalHoliday` and incorrectly referencing an attribute like `self.original_holidays` inside the `_is_holiday` or `_is_holiday_name` method. The base `OriginalHoliday` class does not automatically provide an `original_holidays` attribute for custom data storage.
fix
When creating custom holiday logic, define your holiday data directly within the class or pass it during initialization, and ensure `_is_holiday` and `_is_holiday_name` methods implement the logic to check the input `date` without relying on non-existent attributes. The `JPHoliday` class then registers instances of your custom checker.
```python
import jpholiday
import datetime

class MyCustomHolidayChecker(jpholiday.OriginalHoliday):
    def __init__(self, custom_dates):
        self._custom_dates = custom_dates

    def _is_holiday(self, date):
        return date in self._custom_dates

    def _is_holiday_name(self, date):
        if date == datetime.date(2023, 10, 20):
            return 'Company Anniversary'
        return None # Return None if not a custom holiday for this checker

jph = jpholiday.JPHoliday()
custom_dates_to_add = {datetime.date(2023, 10, 20)}
jph.register(MyCustomHolidayChecker(custom_dates_to_add))

print(jph.is_holiday(datetime.date(2023, 10, 20)))
print(jph.holidays(datetime.date(2023, 10, 20)))
```
ModuleNotFoundError: No module named 'jpholiday'
The `jpholiday` package is not installed in your current Python environment or the environment where your script is being run.
fix
Install the `jpholiday` library using pip.
```bash
pip install jpholiday
```
jpholiday.is_holiday returns False for a known national holiday
This can occur if you are using an outdated version of the `jpholiday` library that does not include the latest national holiday data, or if there was a bug in a specific older version. The library maintains holiday data up to 2026.
fix
Ensure you have the latest version of the `jpholiday` library installed to access the most current holiday data and bug fixes.
```bash
pip install --upgrade jpholiday
```
Upgrade
Version history
1.0.3latest on PyPI · released Dec 26, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
26 hits · last 30 days
node
24
Resources
jpholiday — pip install jpholiday · libregistry