How Firefox Compresses Bookmark Backups into .jsonlz4 Files
Firefox automatically protects user bookmarks by periodically backing
them up into the bookmarkbackups directory using a
specialized .jsonlz4 file format. This article explains the
automated process behind how the browser extracts bookmark data from its
central database, formats the data into JSON, and compresses it using a
custom implementation of the LZ4 algorithm to save disk space and ensure
fast recovery without hindering browser performance.
1. Triggering the Backup and Extracting Data
Firefox stores all active bookmarks and browsing history in a central
SQLite database file named places.sqlite, which is located
in the user's profile folder. To prevent data loss if this database
becomes corrupted, Firefox is programmed to trigger an automatic backup
once a day.
To avoid interrupting the user, the browser waits until it detects an
idle state. Once the system is idle, Firefox's internal
PlacesBackups module queries the places.sqlite
database. It extracts the complete bookmark hierarchy, including
folders, titles, URLs, tags, and creation dates.
2. Serializing Data into JSON
After extracting the raw relational data from the SQLite database, Firefox converts it into a JavaScript Object Notation (JSON) string in the system's memory. JSON is ideal for this task because it natively represents hierarchical tree structures like bookmark folders and is easily parsed by the browser during a restore operation. However, because plain-text JSON files containing thousands of bookmarks can take up significant disk space, Firefox does not write this raw text directly to the hard drive.
3. Applying the Custom LZ4 Compression
To shrink the JSON data, Firefox pipes the in-memory JSON string
through its internal compression API, known as IOUtils
(formerly OS.File). Firefox uses the LZ4 compression
algorithm, which is specifically chosen because it prioritizes extreme
compression and decompression speeds over maximum file-size reduction.
This ensures the daily backup happens instantly in the background with
minimal CPU usage.
Firefox does not use a standard LZ4 file wrapper. Instead, it creates
a proprietary format often referred to as mozLz4. During
the compression process, Firefox constructs the file in memory by doing
the following:
- Adding a Magic Header: It writes a specific 8-byte
header consisting of the ASCII string
mozLz40followed by a null byte (\0). - Recording the Size: It appends a 4-byte little-endian integer that records the exact size of the uncompressed JSON data.
- Compressing the Payload: It compresses the actual JSON string using standard LZ4 block compression and appends it to the header.
4. Deduplication
and Saving to bookmarkbackups
Before writing the compressed data to the
bookmarkbackups directory, Firefox performs a deduplication
check. During the JSON generation phase, the browser calculates a
cryptographic SHA-256 hash of the bookmark data.
Firefox checks the existing files in the bookmarkbackups
folder, which follow a strict naming convention:
bookmarks-YYYY-MM-DD_[item-count]_[base64-hash].jsonlz4.
If the newly generated hash matches the hash in the filename of the
most recent backup, Firefox recognizes that no bookmarks have been
added, deleted, or modified. It then aborts the backup process and
simply updates the date on the existing file. If the hash is different,
Firefox writes the new .jsonlz4 file to the
bookmarkbackups directory. Finally, to prevent the folder
from growing indefinitely, Firefox checks the total number of backups
and automatically deletes the oldest .jsonlz4 files,
keeping only the 15 most recent backups by default.