---
id: zhdate
version: "1.0"
license: unclear
license_treatment: copyleft
maintenance: dormant
---

# zhdate — A pachage to convert Chinese Lunar Calendar to datetime

License: copyleft · Maintenance: dormant · Downloads: 109.3K/mo

## What it is and what it does

ZhDate is a Python library for working with Chinese lunar calendar dates. It performs bidirectional conversion between lunar dates and Gregorian datetime objects entirely through local computation, without calling external APIs. The library represents lunar dates as objects with year, month, and day fields, and supports leap months—a feature of the lunar calendar where an extra month is inserted periodically. It also implements arithmetic operations: you can add or subtract days from a lunar date, or subtract two lunar dates to find the number of days between them.

The package is intended for applications that need to work with traditional Chinese dates—such as calendar systems, holiday calculators, or cultural event scheduling. It has no runtime dependencies and operates as a standalone date-conversion utility. However, the package is dormant (last release January 2023, last commit February 2024) and distributes primarily as a macOS ARM64 wheel, creating significant installation friction on other platforms.

Use it for:

- Convert Chinese lunar calendar dates to Gregorian dates for scheduling or calendar applications.
- Calculate the number of days between two lunar dates or between a lunar and gregorian date.
- Generate lunar calendar displays or holiday calendars that recognize traditional Chinese festivals by lunar date.
- Parse or validate lunar date input in applications serving Chinese-speaking users.
- Perform date arithmetic on lunar dates (e.g., 'what lunar date is 30 days from now').

## Worth the install?

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

Converts between Chinese lunar calendar dates and Gregorian datetime objects without requiring network access, supporting leap months and date arithmetic.

No, unless you are on macOS ARM64 and specifically need lunar calendar conversion. The high install friction (platform-specific wheel, dormant maintenance, unspecified Python version support) and copyleft license (GPLv3+) make it unsuitable for most projects. If you need lunar calendar support on other platforms, verify that the package builds from source or consider alternatives.

## Install

pip install zhdate
uv add zhdate
poetry add zhdate

## Installing zhdate

Before you install: High install friction: the package distributes a pre-built macOS ARM64 wheel as its primary artifact, which will not install on other platforms. Last commit was 2024-02-11 and the project is marked dormant, with no releases since 2023-01-21.

License in practice: Licensed under GPLv3+, a copyleft license requiring that any derivative work or distribution also be licensed under GPL. This restricts use in proprietary or closed-source projects.

Quickstart:

from zhdate import ZhDate
from datetime import datetime

# Create lunar date for 2010 lunar year, month 1, day 1
date1 = ZhDate(2010, 1, 1)
print(date1)  # Prints lunar date string

# Convert lunar to gregorian
dt_date1 = date1.to_datetime()

# Convert gregorian to lunar
dt_date2 = datetime(2010, 2, 6)
date2 = ZhDate.from_datetime(dt_date2)

The package distributes a macOS ARM64 wheel; installation on other platforms (Linux, Windows, or non-ARM macOS) may fail or require building from source. Python version requirements are unspecified.

Verify before relying:

- Whether the package builds successfully on Linux, Windows, or Intel macOS without the prebuilt wheel
- Minimum and maximum Python versions supported (requires_python is empty in metadata)
- Whether the lunar calendar calculations are accurate for dates outside the 2010–2023 range

## Package facts

- License: not declared (copyleft)
- Python support: unspecified
- Install friction: high
- Maintenance: dormant
- Downloads: 109.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

chinese lunar calendar conversion, lunar date to gregorian, zhdate lunar calendar, chinese calendar datetime, lunar calendar arithmetic, 农历日期转换, lunar leap month handling, lunar-calendar, date-conversion, chinese-calendar

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