lunardate

What it is and what it does

Lunardate is a pure-Python library for working with the Chinese calendar system. It provides bidirectional conversion between Gregorian dates and Chinese lunar dates, including support for leap months, and implements date arithmetic (addition and subtraction with timedeltas) and comparison operations. The library has no external runtime dependencies and works with Python 3.7 and later.

The package is designed for applications that need to handle Chinese calendar dates—such as scheduling systems, cultural event planning, or historical date tracking. It exposes a LunarDate class with methods to convert from solar dates, retrieve date components (year, month, day, leap-month status), and perform standard date operations. The implementation is limited to the Chinese calendar years 1900–2099.

Use it for:

• Convert Gregorian dates to Chinese lunar dates for cultural event scheduling or holiday calculations.
• Build calendar applications or date pickers that display both solar and lunar dates for Chinese-speaking users.
• Calculate date differences and perform arithmetic on lunar dates for historical or astrological analysis.
• Determine leap months in the Chinese calendar for a given year to handle calendar irregularities.
• Integrate lunar date support into internationalization or localization workflows for Chinese markets.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts between Gregorian (solar) and Chinese (lunar) calendar dates, with support for leap months and date arithmetic.

Yes. The package is actively maintained, has no dependencies, installs easily, and solves a specific problem with no known vulnerabilities. The copyleft license is a consideration for proprietary projects, but the library is well-suited for open-source or GPL-compatible applications needing Chinese calendar support.

Install

lunardate on PyPI

pip install lunardate

uv add lunardate

poetry add lunardate

Installing lunardate

Before you install

Low friction installation with no runtime dependencies. Actively maintained as of 2026-07-07 with recent release (38 days old).

License in practice

GPL-3.0-or-later copyleft license requires derivative works and distributions to be licensed under GPL-3.0 or later; suitable for open-source projects but may restrict commercial use.

Quickstart

pip install lunardate

from lunardate import LunarDate
import datetime

# Convert Gregorian to lunar
lunar = LunarDate.from_solar_date(1976, 10, 1)
print(lunar)  # LunarDate(1976, 8, 8, 1)

# Convert lunar back to Gregorian
solar = lunar.to_solar_date()
print(solar)  # datetime.date(1976, 10, 1)

# Date arithmetic
ld = LunarDate(1976, 8, 8)
td = datetime.timedelta(days=10)
result = ld + td
print(result)  # LunarDate(1976, 8, 18, 0)

Supports only Chinese calendar years 1900–2099; dates outside this range will not convert correctly.

Verify before relying

• Whether the year range 1900–2099 in the Chinese calendar aligns with common use cases or if users need support outside this window.
• Performance characteristics when performing bulk date conversions or arithmetic on large date ranges.

Package facts

Evidence: lunardate-0.3.0-py3-none-any.whl

Tags

More Python Modules packages