---
id: lunar-python
version: "1.4.8"
license: MIT
license_treatment: permissive
maintenance: aging
---

# lunar_python — lunar is a calendar library for Solar and Chinese Lunar.

License: permissive · Maintenance: aging · Downloads: 81.0K/mo

## What it is and what it does

lunar_python is a zero-dependency calendar library that converts between Gregorian (Western) and Chinese lunar calendars, along with related traditional calendar systems. It computes lunar date components, zodiac animals, stems-and-branches (干支), constellation signs, lucky directions (喜神), festival dates, and other astrological properties. The library is written in pure Python with no external dependencies, making it self-contained but requiring compilation from source during installation.

The package is typically used to display or calculate lunar calendar dates in applications serving Chinese-speaking users, to determine auspicious dates and directions according to traditional practices, or to map between solar and lunar date systems. It supports bidirectional conversion and provides a rich set of computed properties for each date, including festival calendars and traditional fortune-telling attributes.

Use it for:

- Display lunar calendar dates alongside Gregorian dates in applications for Chinese users.
- Determine zodiac animals and astrological properties for a given birth date.
- Calculate auspicious dates and lucky directions for traditional Chinese ceremonies or events.
- Convert between solar and lunar date systems for historical or genealogical records.
- Populate festival and holiday calendars that follow the lunar calendar.

## Worth the install?

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

Converts between Gregorian (solar) and Chinese lunar calendars, and computes associated astrological and traditional calendar properties like zodiac signs, stems-and-branches, lucky directions, and festival dates.

Yes, if you need lunar calendar conversion and astrological properties for a Chinese-language or culturally-aware application. The zero-dependency design and permissive MIT license are strong points. However, the high install friction (source-only distribution) and aging maintenance status (last commit 282 days ago) mean you should verify compatibility with your Python version and build environment before committing. No known vulnerabilities.

## Install

pip install lunar-python
uv add lunar-python
poetry add lunar-python

## Installing lunar_python

Before you install: High install friction: the package is distributed as a source tarball with no pre-built wheels, requiring compilation or manual setup. Maintenance status is aging—last commit was 282 days ago, though the repository remains active and has accumulated 646 stars.

License in practice: MIT license is permissive; you may use, modify, and distribute this package freely in commercial or private projects with minimal restriction, provided you retain the license notice.

Quickstart:

pip install lunar_python

from lunar_python import Lunar

# Initialize lunar calendar from year, month, day
lunar = Lunar.fromYmd(1986, 4, 21)

# Print full lunar date string
print(lunar.toFullString())

# Convert to solar (Gregorian) and print
print(lunar.getSolar().toFullString())

No runtime dependencies, but source-only distribution may require a C compiler or build tools on some systems.

Verify before relying:

- Whether Python version support is truly unspecified or if there is a practical minimum (e.g., Python 3.6+).
- Whether the package works correctly with all modern Python versions or if there are known compatibility issues.
- Performance characteristics when handling large date ranges or bulk conversions.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: high
- Maintenance: aging
- Downloads: 81.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lunar calendar conversion, chinese calendar library, solar to lunar date, zodiac and stems-branches, traditional chinese calendar, lunar date calculator, astrological calendar data, calendar-conversion, chinese-lunar, astrological-data

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