All formats

CHM (Microsoft Compiled HTML Help)

Full nameMicrosoft Compiled HTML Help
Extensions.chm
MIME typeapplication/vnd.ms-htmlhelp
Typearchive of HTML pages, images and indexes, compressed with LZX
Starts with49 54 53 46 (ITSF), then version 03 00 00 00
Specificationnone published by Microsoft; reverse-engineered specification
Maintained byMicrosoft (HTML Help 1.4, no longer developed)
Licenseproprietary format; free open-source readers exist

A CHM file packs a website (HTML pages, CSS, images, scripts) into one compressed file, together with a table of contents, a keyword index and a full-text search index. It was the help format of Windows programs from Windows 98 on, and is still used for software documentation and SDK references and for some e-books, especially Chinese ones.

On Windows, CHM files open in the built-in HTML Help viewer (hh.exe), which renders pages with the old Internet Explorer engine. Because CHM pages can run scripts, CHM files are a common way to deliver malware, and Windows blocks content of CHM files downloaded from the internet.

When to use CHM#

File structure#

A CHM file is a small file system: a header, a directory of named files and the file data, most of it in one LZX-compressed stream. All integers are little-endian.

49 54 53 46               "ITSF" signature
03 00 00 00               version 3
60 00 00 00               header length (0x60)
01 00 00 00               unknown, always 1
xx xx xx xx               timestamp
09 04 00 00               language ID 0x0409 (English, US)
10 FD 01 7C AA 7B D0 11   GUID {7C01FD10-7BAA-11D0-9E0C-00A0C922E6EC}
9E 0C 00 A0 C9 22 E6 EC
11 FD 01 7C ...           GUID {7C01FD11-7BAA-11D0-9E0C-00A0C922E6EC}
...                       offsets and lengths of the 2 header sections, offset of content
Part Contents
ITSF header signature, version, language ID, then a table pointing to 2 header sections and to the content
Header section 0 the total file size
Header section 1 (ITSP) the directory: a B-tree of 4 KB chunks. PMGL chunks list files sorted by name; PMGI chunks index them
Content section 0 uncompressed data: small internal files, and the compressed stream of section 1
Content section 1 (MSCompressed) most files, compressed together with LZX in blocks (usually 32 KB windows with periodic resets for random access)

Each directory entry has a name (UTF-8), a content section number, an offset and a length, all stored as variable-length integers (7 bits per byte, high bit means “more bytes follow”). Offsets refer to the uncompressed content of the section. A reset table (::DataSpace/Storage/MSCompressed/Transform/.../ResetTable) lists where LZX resets happen, so a reader can decompress a file without decompressing everything before it.

Files inside a CHM#

Name Contents
/index.html, /images/... the help pages and their resources, as authored
*.hhc table of contents: an HTML page with nested <ul> lists of <object type="text/sitemap"> items
*.hhk keyword index, same sitemap syntax
/#SYSTEM settings: title, default page, .hhc and .hhk names, language, compiler version
/#TOPICS, /#URLTBL, /#URLSTR, /#STRINGS tables of topics, URLs and strings used by the index and search
/#WINDOWS window definitions (size, buttons, default pane)
/#IDXHDR index header
/$FIftiMain full-text search index
::DataSpace/NameList, ::DataSpace/Storage/... names of the content sections, the LZX control data, reset table and compressed stream

Names starting with / are user files; names starting with :: describe the container. Pages link to each other with relative URLs; from outside, Windows addresses them as mk:@MSITStore:C:\path\help.chm::/page.html or ms-its:help.chm::/page.html.

Working with CHM files#

Specifications and documentation#

Software that opens CHM files#

SoftwareWindowsmacOSLinuxWebCanNotes
SumatraPDF✓viewfree, open source; table of contents and search, without the IE security prompts
Microsoft HTML Help (hh.exe)✓viewbuilt into Windows; Internet Explorer engine
xCHM✓✓✓viewfree, open source, CHMLib-based
uChmViewer✓✓✓viewfree, open source; fork of KchmViewer, also opens EPUB
KchmViewer✓✓✓viewfree, open source, Qt
iChm✓viewfree, open source macOS viewer
Calibre✓✓✓view, convertconverts CHM to EPUB, MOBI, PDF
7-Zip✓✓convertextracts all files from a CHM
archmage✓✓convertCHM to HTML or PDF, command line, Python
HelpNDoc✓createhelp authoring tool, free for personal use

Libraries#

Open-source libraries that read CHM files. See all CHM libraries for a comparison.

C/C++CHMLib, libmspack
Javajchmlib
Pythonpychm
Rustlibchm
PHPchm-lib