---
id: lunarcalendar
version: "0.0.9"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# LunarCalendar — A lunar calendar converter, including a number of lunar and solar holidays, mainly from China.

License: permissive · Maintenance: dormant · Downloads: 707.3K/mo

## What it is and what it does

LunarCalendar is a bidirectional converter between lunar and solar calendar systems, primarily designed for Chinese, Korean, Japanese, and Vietnamese calendars. It converts dates in both directions and provides a built-in festival database covering lunar holidays (Chinese New Year, Mid-Autumn Festival, Dragon Boat Festival), solar holidays with variable dates (Mother's Day, Easter), and 24 solar terms. The package validates date legality (e.g., detecting invalid leap months) and supports both simplified and traditional Chinese language output.

The library covers a fixed time range of 1900 to 2100 and depends on python-dateutil, ephem, and pytz for date arithmetic and astronomical calculations. It includes a console command (lunar-find) for quick festival lookups and is designed to be extended with additional festivals and languages through modification of its festival module.

Use it for:

- Convert a Gregorian date to its lunar calendar equivalent for display in Chinese cultural applications.
- Find the solar date of a lunar festival (e.g., Chinese New Year) for a given year.
- Look up the date of a solar term (e.g., Spring Equinox) using the lunar-find command.
- Validate whether a given lunar date is legal before storing or processing it in a calendar system.
- Generate festival calendars for Chinese, Korean, Japanese, or Vietnamese audiences in their native languages.

## Worth the install?

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

Converts between lunar and solar calendar dates, and provides access to lunar and solar festivals (including Chinese New Year, Mid-Autumn Festival, Easter, and 24 solar terms) for dates between 1900 and 2100.

Yes, if you need lunar-solar conversion and festival data for dates between 1900 and 2100 and can tolerate dormant maintenance. The package is stable, has no known vulnerabilities, installs easily, and covers a common use case well. Not recommended if you require active maintenance, support for dates outside the 1900–2100 range, or frequent updates to festival definitions.

## Install

pip install lunarcalendar
uv add lunarcalendar
poetry add lunarcalendar

## Installing LunarCalendar

Before you install: Low install friction; pure Python wheel with three lightweight runtime dependencies (python-dateutil, ephem, pytz). Dormant maintenance status since June 2018, though the repository remains active with a recent commit in May 2024.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

from lunarcalendar import Converter, Solar, Lunar

solar = Solar(2018, 1, 1)
lunar = Converter.Solar2Lunar(solar)
print(lunar)

Verify before relying:

- Whether the 1900–2100 range and embedded festival data are sufficient for your use case without manual extension.
- Whether the dormant maintenance status (no releases since June 2018) poses a risk for your project's long-term compatibility.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 707.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lunar solar calendar converter, Chinese lunar calendar, lunar festival dates, solar terms calendar, lunisolar calendar conversion, Chinese New Year date finder, lunar date conversion, calendar-conversion, lunar-calendar, festival-data

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