黄历 Huangli: the Chinese almanac in English, with every rule explained
Huangli is a free web app for the traditional Chinese almanac (黄历, also called 通胜, Tong Shu or Tung Shing). It tells you which activities are suitable or to be avoided on any day, and, unlike other almanacs, it shows why: the exact rule, the chapter of the source text, and the original quotation.
What makes it different
- Traceable to a primary source. The daily Suitable / Avoid lists (宜忌) are computed from the imperial Treatise on Harmonizing Times and Distinguishing Directions (欽定協紀辨方書, 1739): its spirit rules, its activity lists, its six-grade table for weighing good spirits against bad ones (宜忌等第表) and its linkage rules (鋪註條例).
- Checked against the book itself. Days from the Treatise's own printed monthly tables (月表) were transcribed from scans and are used as tests; the app's results match them. The lunar calendar is cross-checked over 200 years.
- Follows the Treatise's corrections. Where the Treatise quotes an older list and corrects it in a note (按), the correction is used and the popular variant is shown as an alternative.
- Shows disagreement openly. When some spirits favour an activity and others forbid it, it appears under "Mixed" with the Treatise's verdict, because almanacs that skip the grade table often print the opposite.
- Made for readers new to it. Plain-English summaries, clashing birth years listed by year, and an introduction to yin and yang, the five elements, the ten stems, twelve branches and the sixty-day cycle.
Features
- Suitable, Avoid and Mixed lists for the 60 classical almanac activities, each with its reasoning and sources.
- My activities: modern plans such as a job interview, starting a new job, signing a contract, moving house, a wedding, a birthday party, a business trip or a product launch, mapped to the classical activities by purpose with the reason shown, rated for each day, with the next suitable days. You can describe your own; matching happens on your device.
- Non-physical work (software, office work) skips the taboos that concern only digging and building.
- Chinese lunar date, leap months and the 24 solar terms, computed astronomically.
- Year, month, day and hour pillars; day officer (建除); yellow and black path spirits; 28 lunar mansions; clash and sha direction; nayin; Pengzu's taboos; all auspicious and inauspicious spirits.
- Good and bad double-hours (时辰) on true local solar time.
- Optional southern-hemisphere reading.
- Weather for your city or US ZIP code: today, a 16-day forecast and recent history.
- Ambient mode for a spare tablet or TV: clock and almanac with OLED protection, a plain background in any colour, Wang Xizhi's Preface to the Orchid Pavilion and Ouyang Xun's Sweet Spring of Jiucheng Palace, shown piece by piece or your own pictures.
- English or Simplified Chinese, light or dark, Western or Chinese colours for good and bad, custom date formats, swipe or arrow keys to change the day.
- Install it as an app on Chrome, Edge, Android, iPhone, iPad or Mac; it works offline.
Good for
- Choosing a date for a wedding, a move, opening a business, signing a contract, travel, surgery or a new job, as the almanac has traditionally been used.
- English speakers and the Chinese diaspora who want to understand what the almanac says and why.
- Students and researchers of Chinese calendrics who want rules tied to the primary text.
- A calm, always-on calendar display.
How to read it
"Suitable" and "Avoid" are the Treatise's verdicts for its 60 classical activities. The mappings from modern activities are the app's own interpretations and are labelled as such. "Lucky day" refers only to the yellow-path count and does not override the day's spirits. The almanac is a cultural tradition, not a guarantee of outcomes.
Disclaimer
For entertainment and cultural interest only. Huangli shows what a traditional Chinese almanac says. It is not medical, health, legal, financial, relationship or any other professional advice, and it does not predict or guarantee any outcome. Do not rely on it for real-life decisions; consult a qualified professional. You use it at your own risk.
Privacy
No accounts, cookies, analytics or ads. Everything is calculated on your device and settings stay in your browser. Only a chosen weather place's coordinates are sent (to Open-Meteo).
Sources
欽定協紀辨方書 (1739, Siku Quanshu edition; Wikisource, Kanseki Repository and CADAL scans), GB/T 33661-2017, Astronomy Engine, Open-Meteo, public-domain calligraphy scans, and the National Palace Museum, Taipei (open data). Full credits are in the app under Sources and credits.
Contact: contact@chinesehuangli.com · chinesehuangli.com · llms.txt