vi-lunaire 2026.4.11

Vietnamese Solar-Lunar calendar converter with CLI and iCal export

vi-lunaire

Vietnamese Solar-Lunar calendar converter. Convert dates between the Gregorian calendar and the Vietnamese lunar calendar (Âm lịch), look up holidays, and export lunar events to iCal files for Apple and Google Calendar.

Install

pip install vi-lunaire

Or with uv:

uv tool install vi-lunaire

CLI

The CLI is available as vi-lunaire, vilunaire, or clv — all three are identical.

Convert dates

Solar to lunar:

$ vi-lunaire convert 2025-01-29

☀️ Solar              →    🌙 Lunar
2025-01-29                 01/01/2025 (Ất Tỵ)

Tết Nguyên Đán

Lunar to solar:

$ vi-lunaire convert --lunar 2025-01-01

🌙 Lunar              →    ☀️ Solar
01/01/2025 (Ất Tỵ)        2025-01-29

For leap months, add --leap:

$ vi-lunaire convert --lunar --leap 2023-02-15

List holidays

$ vi-lunaire holidays 2025

🌙 Vietnamese Lunar Holidays — 2025 (Ất Tỵ)

┌─────────────────────────┬───────┬────────────┐
│ Holiday                 │ Lunar │ Solar      │
├─────────────────────────┼───────┼────────────┤
│ Tết Nguyên Đán          │ 01/01 │ 2025-01-29 │
│ Tết Nguyên Đán (Mùng 2) │ 01/02 │ 2025-01-30 │
│ Tết Nguyên Đán (Mùng 3) │ 01/03 │ 2025-01-31 │
│ Tết Nguyên Tiêu         │ 01/15 │ 2025-02-12 │
│ Tết Hàn Thực            │ 03/03 │ 2025-03-31 │
│ Lễ Phật Đản             │ 04/15 │ 2025-05-12 │
│ Tết Đoan Ngọ            │ 05/05 │ 2025-05-31 │
│ Vu Lan                  │ 07/15 │ 2025-09-06 │
│ Tết Trung Thu           │ 08/15 │ 2025-10-06 │
│ Ông Công Ông Táo        │ 12/23 │ 2026-02-10 │
└─────────────────────────┴───────┴────────────┘

List custom events

Define recurring lunar events in a YAML, JSON, or CSV file:

# family.yaml
events:
  - name: "Giỗ Ông Nội"
    lunar_month: 3
    lunar_day: 10
    type: gio
  - name: "Tết Trung Thu"
    lunar_month: 8
    lunar_day: 15
    type: holiday

Then resolve them to solar dates for a given year:

$ vi-lunaire events --file family.yaml --year 2025

🌙 Lunar Events — 2025 (Ất Tỵ)

┌──────────────┬──────────┬───────┬────────────┐
│ Event        │ Type     │ Lunar │ Solar      │
├──────────────┼──────────┼───────┼────────────┤
│ Giỗ Ông Nội  │ gio      │ 03/10 │ 2025-04-07 │
│ Tết Trung Thu │ holiday │ 08/15 │ 2025-10-06 │
└──────────────┴──────────┴───────┴────────────┘

JSON and CSV work too:

{
  "events": [
    {"name": "Giỗ Ông Nội", "lunar_month": 3, "lunar_day": 10, "type": "gio"}
  ]
}

name,lunar_month,lunar_day,type
Giỗ Ông Nội,3,10,gio
Tết Trung Thu,8,15,holiday

Export to iCal

Generate .ics files to import into Apple Calendar or Google Calendar:

# Holidays only
vi-lunaire ical --holidays --year 2025 -o holidays.ics

# Your events only
vi-lunaire ical --file family.yaml --year 2025 -o family.ics

# Both
vi-lunaire ical --file family.yaml --holidays --year 2025 -o 2025.ics

Import the .ics file into your calendar app and share it with anyone.

Python API

from vi_lunaire import solar_to_lunar, lunar_to_solar

# Solar to lunar
lunar = solar_to_lunar(2025, 1, 29)
lunar.month    # 1
lunar.day      # 1
lunar.can_chi  # "Ất Tỵ"
lunar.leap     # False

# Lunar to solar
solar = lunar_to_solar(2025, 1, 1)  # datetime.date(2025, 1, 29)

# Leap month
solar = lunar_to_solar(2023, 2, 15, leap=True)

Holidays

from vi_lunaire import get_holidays

for h in get_holidays(2025):
    print(f"{h.name}: {h.solar_date}")

Events

from vi_lunaire import load_events, get_events_for_year

events = load_events("family.yaml")
for e in get_events_for_year(events, 2025):
    print(f"{e.name}: {e.solar_date}")

iCal

from vi_lunaire import load_events, get_holidays, get_events_for_year, generate_ical

events = get_events_for_year(load_events("family.yaml"), 2025)
holidays = get_holidays(2025)
generate_ical(events=events, holidays=holidays, year=2025, output="2025.ics")

How it works

The conversion uses Hồ Ngọc Đức's algorithm structure with Jean Meeus's new moon formula for better accuracy on modern dates. All calculations use Vietnamese timezone (UTC+7), which means lunar dates may occasionally differ by one day from the Chinese lunar calendar.

Supported year range: 1900-2100.

License

MIT