Âm Lịch Việt Nam cho Python 🇻🇳

lunar-vn là thư viện Python siêu nhẹ, typed, không có phụ thuộc, dùng để lấy âm lịch Việt Nam, tra ngày lễ phổ biến và tính Can Chi.

Module này được thiết kể cho:

• Ứng dụng lịch âm Việt Nam.
• Tích hợp vào hệ thống nhân sự, chấm công, đặt lịch, sự kiện.
• Bot hoặc backend cần ngày âm lịch Việt Nam.
• Ưu tiên sự chính xác, đơn giản, gọn nhẹ.
• CLI ngay trên terminal.

Tính năng

• Không có dependency runtime.
• Hỗ trợ type hint và PEP 561 (py.typed).
• Chuyển đổi dương lịch sang âm lịch và ngược lại.
• Hỗ trợ tháng nhuận chính xác.
• Múi giờ mặc định UTC+7 theo Việt Nam.
• Tính Can Chi năm, tháng, ngày, giờ.
• Liệt kê, tra cứu ngày lễ dương lịch và âm lịch phổ biến ở Việt Nam.
• CLI lunar-vn với output text hoặc JSON.
• Khoảng ngày dương lịch hỗ trợ: 1900-01-01 đến 2100-12-31.

Cài đặt

pip install lunar-vn

CLI

Xem âm lịch hôm nay:

lunar-vn today

Đổi dương lịch sang âm lịch:

lunar-vn solar 2026-02-17

Đổi âm lịch sang dương lịch:

lunar-vn lunar 1 1 2026

Liệt kê ngày lễ trong năm dương lịch:

lunar-vn holidays 2026

Xem Can Chi theo ngày dương lịch:

lunar-vn canchi 2024-02-10

Thêm --json vào cuối lệnh để nhận dữ liệu JSON:

lunar-vn solar 2026-02-17 --json

Ví dụ JSON:

{"holiday": "Tết Nguyên Đán", "lunar": {"day": 1, "leap": false, "month": 1, "year": 2026}, "solar": "2026-02-17"}

Với tháng âm lịch nhuận, dùng --leap:

lunar-vn lunar 1 2 2004 --leap

Sử dụng trong Python

Chuyển đổi cơ bản

import datetime as dt
from lunar_vn import solar_to_lunar, lunar_to_solar, LunarDate

# Tết nguyên đán
solar_date = dt.date(2026, 2, 17)
lunar_date = solar_to_lunar(solar_date)

print(lunar_date) # LunarDate(day=1, month=1, year=2026, leap=False)

# Lunar -> Solar
print(lunar_to_solar(LunarDate(1, 1, 2026))) # 2026-02-17

Âm lịch hôm nay

import datetime as dt
from lunar_vn import solar_to_lunar

today = dt.date.today()
lunar = solar_to_lunar(today)

print(f"Solar: {today}")
print(f"Lunar: {lunar.day}/{lunar.month}/{lunar.year}")
print(f"Leap month: {lunar.leap}")

Can Chi và ngày lễ

import datetime as dt
from lunar_vn import can_chi, holidays, jd_from_date, list_holidays, solar_to_lunar

date = dt.date(2024, 2, 10)
lunar = solar_to_lunar(date)

# Lấy năm Can Chi
print(can_chi.get_year_can_chi(lunar.year))  # Giáp Thìn

# Lấy ngày Can Chi
jdn = jd_from_date(date.day, date.month, date.year)
print(can_chi.get_day_can_chi(jdn))  # Giáp Thìn

# Kiểm tra ngày lễ
print(holidays.get_holiday(date))  # Tết Nguyên Đán

# Danh sách ngày lễ Dương lịch
for solar_date, name in list_holidays(2026):
    print(solar_date, name)

Ngày lễ Việt Nam

lunar-vn có sẵn một tập ngày lễ dương lịch và âm lịch phổ biến.

Ngày lễ dương lịch:

• Tết Dương Lịch
• Ngày Lễ Tình Nhân (Valentine)
• Ngày Quốc Tế Phụ Nữ
• Ngày Giải Phóng Miền Nam
• Ngày Quốc Tế Lao Động
• Ngày Quốc Tế Thiếu Nhi
• Ngày Quốc Khánh
• Ngày Phụ Nữ Việt Nam
• Ngày Nhà Giáo Việt Nam
• Ngày Thành Lập Quân Đội Nhân Dân Việt Nam
• Lễ Giáng Sinh

Ngày lễ âm lịch:

• Tết Nguyên Đán
• Rằm Tháng Giêng
• Tết Hàn Thực
• Giỗ Tổ Hùng Vương
• Lễ Phật Đản
• Tết Đoan Ngọ
• Lễ Thất Tịch
• Lễ Vu Lan
• Tết Trung Thu
• Tết Hạ Nguyên
• Tết Ông Công Ông Táo

Các nhắc lịch âm phổ biến mỗi tháng:

• Mùng 1
• Rằm

Benchmark

Chạy benchmark:

PYTHONPATH=src python3 scripts/benchmark.py

Kỳ vọng: hơn 100.000 lượt chuyển đổi mỗi giây trên máy phổ thông.

Độ chính xác và phạm vi

lunar-vn tập trung vào các nhu cầu cốt lõi của âm lịch Việt Nam: chuyển đổi ngày, Can Chi và ngày lễ phổ biến. Thư viện không mở rộng sang Vạn Sự, tử vi, giờ hoàng đạo hoặc chọn ngày tốt để API nhỏ, rõ và dễ kiểm chứng.

Khoảng ngày dương lịch hỗ trợ là 1900-01-01 đến 2100-12-31. Test suite có kiểm tra roundtrip dương lịch -> âm lịch -> dương lịch trong toàn bộ khoảng này.

So sánh với âm lịch Trung Quốc

Xem tài liệu tại docs/comparison_chinese_lunar.md.

Nguồn

Thuật toán âm lịch Việt Nam dựa trên đặc tả của Hồ Ngọc Đức tại: https://xemamlich.uhm.vn

Thư viện này là bản triển khai lại bằng Python của thuật toán đã công bố.

License

MIT License.