Registry / productivity / chinese-calendar

chinese-calendar

library1.11.0pypypi✓ verified 85d ago

Python library to check whether a given date is a holiday or workday in China, based on the official government announcements. Current version 1.11.0, released 2025-03-10. Active development, ~2 releases per year.

productivity

pip install chinese-calendar

github ↗homepage ↗

INSTALL

IMPORT

SIG · CHINESE-CALENDAR

chinese-calendar

productivitypythonv1.11.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

is_holiday

✓ from chinese_calendar import is_holiday

✗ from chinese_calendar import isHoliday

Function names are snake_case, not camelCase

is_workday

✓ from chinese_calendar import is_workday

get_holiday_detail

✓ from chinese_calendar import get_holiday_detail

✗ from chinese_calendar import getHolidayDetail

Function names are snake_case

Basic usage: check holidays, workdays, and get holiday names.

from datetime import date from chinese_calendar import is_holiday, is_workday, get_holiday_detail # Check today today = date.today() print(f"Is {today} a holiday? {is_holiday(today)}") print(f"Is {today} a workday? {is_workday(today)}") # Get detailed info on_holiday, holiday_name = get_holiday_detail(date(2026, 1, 1)) print(f"Jan 1, 2026: holiday={on_holiday}, name={holiday_name}") # Check for future dates from datetime import timedelta for i in range(1, 10): d = date.today() + timedelta(days=i) if is_holiday(d): _, name = get_holiday_detail(d) print(f"{d}: {name} holiday")

Debug

Known issues

gotchaThe library only includes dates that have been officially announced. Holidays for the current year may not be fully published until late in the previous year or early in the current year. For future years, results may be incomplete or incorrect until the Chinese government releases the official holiday schedule.

fix

Always check the official Chinese government holiday announcement for the year. The library may lag behind the announcement.

affects: all

deprecatedThe function `isHoliday` (camelCase) was deprecated in version 1.0.0 and removed in version 1.8.0. Use `is_holiday` (snake_case) instead.

fix

Replace `isHoliday(date)` with `is_holiday(date)`.

affects: >=1.8.0

gotchaThe library uses the `lunar_date` function from `lunardate` for some calculations. If you use `chinese_calendar` with custom lunar dates, ensure `lunardate` is installed (it is a dependency, but check version compatibility).

fix

Install chinese-calendar normally; pip should install lunardate automatically. If you see ImportError for lunardate, install it explicitly: `pip install lunardate`.

affects: all

gotcha`is_workday` returns False for holidays and also for weekends (Saturday/Sunday) unless they are designated as compensation workdays (调休). Similarly, `is_holiday` returns True for weekends that are part of a holiday period. This can be confusing if you expect only national holidays.

fix

Use `get_holiday_detail` to distinguish between actual holidays (e.g., Spring Festival) and regular weekends. `is_workday` will be True only for days that are officially workdays (including compensation workdays on weekends).

affects: all

Errors

Common errors & fixes

ImportError: cannot import name 'isHoliday' from 'chinese_calendar'

The function name uses snake_case, not camelCase. `isHoliday` was removed in v1.8.0.

fix

Use `from chinese_calendar import is_holiday` instead.

AttributeError: module 'chinese_calendar' has no attribute 'get_holiday_detail'

The function is named `get_holiday_detail` (snake_case). Might be using an older version (<0.5.0) or wrong import.

fix

Ensure you have the latest version: `pip install --upgrade chinese-calendar`. Then use `from chinese_calendar import get_holiday_detail`.

TypeError: is_holiday() missing 1 required positional argument: 'date'

The function requires a `datetime.date` object, not a string.

fix

Convert your date string to a `date` object: `from datetime import datetime; my_date = datetime.strptime('2026-01-01', '%Y-%m-%d').date(); is_holiday(my_date)`.

ValueError: year 2026 is out of range (1901, 2099)

The underlying `lunardate` library (used for lunar calendar conversions) only supports years between 1901 and 2099.

fix

Ensure the date is within the supported range. If you need dates outside this range, consider another library or handle manually.

Upgrade

Version history

1.11.0latest on PyPI · released Nov 4, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

63 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/LKI/chinese-calendar ↗

homepagehttps://github.com/LKI/chinese-calendar ↗