---
id: korean-lunar-calendar
version: "0.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# korean-lunar-calendar — Convert the Korean lunar calendar to/from the Gregorian solar calendar (KARI standard).

License: permissive · Maintenance: active · Downloads: 6.7M/mo

## What it is and what it does

korean_lunar_calendar is a stateful date converter that transforms dates between the Korean lunar calendar (음력) and the Gregorian solar calendar (양력). It bundles the conversion table offline, requires no network calls, and follows the KARI (Korea Astronomy and Space Science Institute) standard—the same astronomical basis as the Chinese lunar calendar, but using Korean-specific intercalation rules. The library handles leap months (윤달), the 1582 Gregorian reform gap, and provides output in both Korean and Chinese sexagenary cycle notation.

You instantiate a KoreanLunarCalendar object, call setSolarDate() or setLunarDate() to set a date (both return a bool to indicate success), and then read the result back in the other calendar via LunarIsoFormat(), SolarIsoFormat(), getGapJaString(), or getChineseGapJaString(). Input validation is strict: out-of-range dates, non-integers, and impossible leap months are rejected. The library has no third-party dependencies and requires Python 3.6 or later.

Use it for:

- Convert Korean holidays and traditional dates (e.g., Lunar New Year) to Gregorian dates for scheduling and calendar applications.
- Display sexagenary cycle strings (GapJa) in Korean or Chinese for cultural or astrological contexts.
- Validate lunar dates in user input and reject impossible or out-of-range dates before processing.
- Build calendar or genealogy tools that work with both lunar and solar date systems.
- Integrate lunar calendar support into event management or historical record systems.

## Worth the install?

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

Converts dates between the Korean lunar calendar and Gregorian solar calendar following the KARI standard, entirely offline with no external dependencies.

Yes. The package is actively maintained, has zero known vulnerabilities, imposes no dependency burden, and solves a specific problem (Korean lunar–solar conversion) with a well-defined, validated API. Install it if you need to work with Korean lunar dates; skip it if you only need Gregorian calendars.

## Install

pip install korean-lunar-calendar
uv add korean-lunar-calendar
poetry add korean-lunar-calendar

## Installing korean-lunar-calendar

Before you install: Low friction: pure Python with no runtime dependencies, distributed as a wheel, and actively maintained with a recent release.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open and proprietary projects.

Quickstart:

pip install korean_lunar_calendar

from korean_lunar_calendar import KoreanLunarCalendar

calendar = KoreanLunarCalendar()
if calendar.setSolarDate(2017, 6, 24):
    print(calendar.LunarIsoFormat())  # 2017-05-01 Intercalation

Supported date range: lunar 1000-01-01 to 2050-11-18, solar 1000-02-13 to 2050-12-31; dates outside this range will cause setters to return False.

Verify before relying:

- Whether the KARI conversion tables are updated annually or on a fixed schedule.
- Performance characteristics for bulk conversions or real-time calendar applications.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

korean lunar calendar conversion, lunar to solar date converter, korean calendar library, lunar calendar python, kari lunar solar conversion, korean 음력 양력 converter, intercalation leap month calendar, calendar-conversion, korean-culture, offline-data

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