DictShelf

README

DictShelf

DictShelf is a cross-platform dictionary app. Its source, releases and maintained documentation live in the DMSHLabs/DictShelf repository. The app is a fast, native, self-contained, multi-format dictionary server that runs in your browser at http://localhost:6888.

DictShelf began as a fork of the WuWeiDict project (wuweidict/wudict) and keeps its format support, its GPL-3.0-or-later licence and the upstream copyright notices in every file upstream wrote. What the fork adds is its own product identity and platform work:

• Its own Android identity — package com.dmshlabs.dictshelf, launcher name DictShelf — so it installs and runs beside the upstream wudict app.
• Android-focused UI work: an extended Appearance sheet (window background color and image, CSS presets as toggleable layers), a native folder picker, and ongoing reliability fixes.
• The files this fork authored carry its own notice — Copyright (C) 2026 DmShAl (Shepeta Dmitry) — under the same licence.

Desktop builds and the general manual live in this repository. To build the Android app from source, see the Android build instructions.

Runs on Android, macOS, Linux, Windows.

One native golang binary, no dependencies and minimum configuration — just set the folders with your .mdx/.slob/.bgl/.zim/.ifo dictionary collections, and you are good to go.

Runs natively on android, mac, windows, linux, and even raspberry pi.

Supported formats

Format	Files	Notes
MDict	.mdx + .mdd	companion *.mdd, *.1.mdd, … resource archives; built-in .spx audio decoding
StarDict	.ifo + .idx(.gz) + .dict(.dz)	.syn synonyms, res/ folder or res.zip resources
Aard2	.slob	zlib/bz2/lzma2; embedded images/audio/css
Lingvo DSL	.dsl, .dsl.dz	UTF-8/16/32 auto-detected; *.dsl.files.zip resources
Babylon	.bgl	gzip block stream; source/target charset auto-detected (Latin / Cyrillic / CJK code pages); embedded images
ZIM	.zim	Kiwix/Wikimedia offline archives; see https://library.kiwix.org
wudict markdown	.wudict.md or .md, .wudict.md.gz	plain CommonMark, readable and editable in any editor; a dictionary only when its first two lines are # Title and wudict: 1, whatever the name; <name>.wudict.files/ resources; written by dictshelf dump -format md
DictShelf	cache folder (text.db)	DictShelf's own SQLite-based format (see Sharing, below)

DictShelf for Desktop

1. Download the standalone binary for your OS from releases, rename to dictshelf, chmod +x dictshelf (macOS/Linux) and move to a folder in $PATH, e.g. /usr/local/bin.
2. Run dictshelf or ./dictshelf if the file is in the current folder. For Windows, use the dictshelf-windows-x64-setup-<version>.exe installer or the DictShelf.exe desktop build. For macOS an app bundle is provided (it is not signed with a commercial Apple Developer Certificate, macOS flags it as unverified, and extra steps are needed to de-quarantine the app as described in the manual).
3. By default dictshelf searches for dictionaries under ~/Dictionaries (including subfolders); if the dictionary folder is missing or empty, a setup page opens where you can configure your dictionary folders.

Adding dictionaries

With DictShelf running, dictionary folders can be configured from http://localhost:6888/setup. The browser setup page is a convenience for writing DICT_DIR in the configuration file at ~/.dmshlabs/dictshelf/dictshelf.toml and other actions, such as configuring lemmatization (morphology), installing dictionaries from a URL via drag-n-drop from the system file manager.

Multiple dictionary folders

You can configure the dictionary folders from the console via cli args, env vars or by directly editing the config file at ~/.dmshlabs/dictshelf/dictshelf.toml (recommended):

# as one or more CLI args (for example, as a temporary override of the current `dictshelf.toml`):
dictshelf --dict-dir ~/Dictionaries --dict-dir /Volumes/Data/Dicts   # repeat the flag

# or via an env var:
DICT_DIR="~/Dictionaries:/Volumes/Data/Dicts" dictshelf              # separate multiple folders with ":" on linux/mac and ";" on Windows

in dictshelf.toml (the recommended way):

DICT_DIR = ["~/Dictionaries", "/Volumes/Data/Dicts"]

Searching

Mode	What it does	Needs indexing?
starts with	exact matches, else headwords starting with the term (accent/case-insensitive)	no
exact	exact headword (accent/case-fold fallback: corazon → corazón)	no
contains	substring / typo-tolerant headword match, anywhere in the word (FTS5 trigram)	ad-hoc
full-text	search inside article text, ranked by relevance	yes

When you add a dictionary, DictShelf queues its headword index in the background. Until the index is ready, exact and prefix searches use the dictionary's own format. The library index makes lookups faster and supports accent-insensitive search (corazon → corazón). Search does not start an index job.

Full-text (searching inside article text) and contains (substring search) are not enabled by default as they consume more disk space. Click the ☰ button and enable them as needed. For each dictionary the index size is displayed; ⚡ index all adds full-text for all dictionaries at once, and dictshelf ingest [-fulltext] [-contains] [<file-or-folder>] does the same from the command line.

Results stream live as each dictionary responds — the top one opens automatically. In the ☰ panel you can reorder dictionaries (drag the ⠿ handle or use the ▲▼⏫⏬ buttons) to set your preferred result order, and enable/disable each one (the switch) to include or exclude it from All dictionaries searches; both are remembered. A dictionary that was disabled for All dictionaries searches can still be searched by selecting it in the dictionary dropdown.

[!TIP]

• Pressing / focuses the search box
• double-click any word in an article to look it up
• click links inside articles to follow cross-references
• audio plays on click
• ⊞ expands all results (⊟ closes them again — for the current page only, never remembered)
• ⇔ toggles a wide layout
• ☀☾ cycles auto/light/dark theme. Search URLs are bookmarkable

Run as an app (macOS)

For macOS you can either run the dictshelf binary from a terminal, or use the dictshelf-macos-universal-app-<version>.zip from releases which wraps dictshelf into a macOS app bundle.

[!WARNING] The macOS bundle is signed with an ad-hoc certificate therefore on first run the bundle has be de-quarantined with /usr/bin/xattr -cr /Applications/DictShelf.app and then launched via righ-click → Open.

Run DictShelf as a service (macOS)

dictshelf can be installed as a launchctl LaunchAgent using Makefile targets:

# run from project root
make mac-agent-install   # generate the plist from launchctl/*.plist.in, then:
make mac-agent-start     # launchctl bootstrap gui/$UID <plist>
make mac-agent-stop      # launchctl bootout   gui/$UID/com.dmshlabs.dictshelf
make mac-agent-restart   # rebuild, then launchctl kickstart -k gui/$UID/<label>
make mac-agent-status    # launchctl print    gui/$UID/<label>
make mac-agent-uninstall # stop it and delete the plist

Run as an app (Windows)

On Windows, DictShelf.exe opens the WebView2 desktop window without a console window. The same executable handles terminal commands, for example DictShelf.exe --help; run it from PowerShell or cmd to see command output. It also shows a tray icon; closing the window leaves the server running in the tray. Exit in Settings or Quit in the tray stops the server. If the WebView2 Runtime is absent, it opens the default browser instead. Logs go to %USERPROFILE%\.dmshlabs\dictshelf\db.logs\dictshelf.log. See also running on Windows.

Run as a service (Linux)

On linux dictshelf can be installed as a systemd user unit — only copying the binary into /usr/local/bin needs sudo, the service itself runs with user permissions and start/stop does not require sudo. Unlike system services which are managed via systemd start|stop|status <service-name>, a user systemd service additionally requires the --user key, e.g. systemd --user start|stop|status dictshelf.

# from project root
make linux-service-install   # sudo-installs /usr/local/bin/dictshelf, then writes the user unit
make linux-service-start     # systemctl --user enable --now dictshelf.service
make linux-service-stop
make linux-service-restart   # rebuild, reinstall the binary, restart
make linux-service-status
make linux-service-uninstall # disable + remove the unit (keeps the binary)

make linux-install     # just the binary  (PREFIX=/opt/foo to relocate)
make linux-uninstall

The systemd unit assumes the executable is at /usr/local/bin/dictshelf.

To keep the service running when you are not logged in:

sudo loginctl enable-linger "$(id -un)"

Configuration

Priority: CLI flag > environment variable > dictshelf.toml > default. A commented ~/.dmshlabs/dictshelf/dictshelf.toml is generated on first run, and the config file path is printed on startup.

Flag	env / toml key	Default
--dict-dir	DICT_DIR	~/Dictionaries
--db-dir	DB_DIR	~/.dmshlabs/dictshelf/db
--ip	SERVER_IP	127.0.0.1
--port	SERVER_PORT	6888
--config	CONFIG_PATH	auto-detect
--no-browser	NO_BROWSER=1	open the app window or browser
--verbose	VERBOSE=1	detailed logging
--speexdec	SPEEXDEC	found on PATH
--use-cached	USE_CACHED	off
—	BROWSER_EXTENSIONS	any extension may look words up

BROWSER_EXTENSIONS sets which browser extensions may use the dictshelf server. Blank (the default) lets any installed extension reach the read-only dictionary API — /api/dicts, /api/search, /res/.

Restrict to only allow specific extensions:

BROWSER_EXTENSIONS = ["chrome-extension://bknaaoffefipfnpefmkbipcdemljbhjh"]

(Firefox generates a fresh moz-extension:// id for every installation, so there is no stable origin to pin there.)

See also: browser extensions

Config file search order: --config / CONFIG_PATH, then <exe-dir>/dictshelf.toml, ~/.dmshlabs/dictshelf/dictshelf.toml, /etc/dictshelf/dictshelf.toml.

Portable mode. A dictshelf.toml can also be placed in the same folder as the dictshelf (or DictShelf.exe) executable.

~/.dmshlabs/dictshelf/state.json stores dictionary search order and enabled/disable state.

Command line

Run dictshelf --help for the full reference.

Examples:

dictshelf                                   # start the server (default command)

# start server with custom options
dictshelf --dict-dir ~/Dicts --port 9090
dictshelf --dict-dir ~/Dicts --dict-dir /Volumes/Ext/Dicts   # several folders

# search for a word in a specific dictionary; plain text to stdout 
# optional, request specific format with: "-format=raw|clean|text"
dictshelf lookup ~/Dicts/Oxford.mdx water

# search ALL dictionaries in folder; plain text to stdout
dictshelf searchall -dict-dir /path/to/dicts flight

# index every dictionary in your configured folders (DICT_DIR), as the app does
dictshelf ingest

# index every dictionary in a given folder
dictshelf ingest ~/Dicts

# index + pack media
dictshelf ingest -full ~/Dicts/Oxford.mdx

# clean leftover files
dictshelf clean

# list removable library items (-f deletes)

# list headwords (or keys) in a specific dictionary
dictshelf keys ~/Dicts/Oxford.mdx
dictshelf keys ~/Dicts/Oxford.mdd

# extract a resource (pass the key shown by `dictshelf keys ...`)
dictshelf res ~/Dicts/Oxford.mdd audio/a.mp3

For more on command line usage see the manual:

• DictShelf Command Line

Sharing dictionaries (one folder each)

Indexing a dictionary creates a corresponding folder under ~/.dmshlabs/dictshelf/db/ — the library:

~/.dmshlabs/dictshelf/db/
  Oxford/
    text.db     articles + search indexes
    media.db    audio/images (only after "pack media")
    info.txt    what this is, where it came from
    res/        optional — files that override the dictionary's own original resources

A dictionary is one folder, so it moves as one thing: copy, move or zip it and share. On the other machine, drop it into a dictionary folder and it works — no original source files needed. a text.db without its media.db still works (with no media). To generate the media pack click the media in the dictionary panel.

The ☰ panel shows each dictionary's provenance: the source file it came from, and — expanded — the library folder holding its SQLite database files. Click a path to copy it to clipboard.

At the foot of the panel, Folders & configuration shows which folders are being scanned (with per-folder counts), where indexed dictionaries are located, and which dictshelf.toml is in effect — with Reveal in Finder / Show in File Explorer / Open Containing Folder, depending on your system. Edit folders… opens the dictionary folders editor.

Patching dictionary's files

Dictionaries can include their own stylesheets, scripts, images and audio. You can provide your own 'patched' versions by placing files in the res/ subfolder in DictShelf's DB folder at ~/.dmshlabs/dictshelf/db/<some-dict-name/res. Files from ./res take precedence over the original files from .mdd, .slob, .dsl.files.zip etc.

~/.dmshlabs/dictshelf/db/Cambridge English Dictionary Online/
  text.db
  res/
    jquery.js          ← replaces the dictionary's own (damaged) copy
    js/entry.js        ← supplies one the dictionary never contained
    css/style.css

Subfolders must follow the same hierarchy as the original resources. E.g. intermediary folders like js/… and css/… must mirror the path the article is referencing.

One exception: a .spx audio file placed in res/ is served as-is, not transcoded to WAV the way a .spx inside the dictionary is. Use .mp3 or .wav instead.

Custom styles

res/ patches one file of one dictionary. To restyle everything — DictShelf itself and every article — put your own CSS in two optional files beside the dictshelf.toml in effect, usually ~/.dmshlabs/dictshelf/style/:

~/.dmshlabs/dictshelf/style/
  app.css       dictshelf itself — its colours, its own layout
  article.css   what dictionaries render, in every article

The ☰ panel's Custom styles… opens an editor for app and article styles, docked at the bottom of the page so you get live preview of your CSS changes as you type. A few presets are included — a compact mobile view, sepia, high contrast, true-black OLED, a wider column, justified text, normalized tables.

/* app.css — sepia in light mode, page and definitions together */
html:not([data-dark]){
  --bg:#f4ecd8; --bg-card:#faf3e3;
  --fg:#3b3229; --line:#e0d5bd;
  --wd-article-bg:#faf3e3; --wd-article-fg:#3b3229;
}

/* article.css — reclaim the side space a desktop dictionary reserves */
@media (max-width: 700px){
  :host, :root > body         { margin-inline:0 !important; padding-inline:0 !important }
  :host > *, :root > body > * { margin-inline:0 !important; padding-inline:0 !important }
}

To undo changes use ⌘ + Z (on windows Ctrl + Z). A dot on a tab means that box has unsaved changes. If a rogue CSS rule makes the app UI disappear, append /?style=off in the URL and the page is served with default styles.

Disk use

A prepared dictionary is usually smaller than the original dictionary file: article bodies are compressed, and full-text search and contains indexes are only built on-demand.

index type	cost (40k-entry dictionary, 45.6 MB source)
regular search — exact, prefix, accent-insensitive	~2 MB, always on
full-text search	~12 MB, one click
contains (substring)	~2.4 MB, one click
packed media	as large as the images/audio

The ☰ panel shows these as switches per dictionary, with their real sizes — click to add, click again to remove.

Article text in prepared dictionaries is compressed when that reduces its size.

Speex audio (.spx)

Browsers cannot play Speex. DictShelf internally transcodes .spx audio to WAV and caches the result, with the decoder built in. With SPEEX_BACKEND=external the external speexdec utility is used instead (for mac: brew install speex, linux: apt install speex, etc).

Building from source

Requires Go (and a C compiler for the default cgo build):

make build          # native build (cgo sqlite, fastest) → ./dictshelf
make install        # install the binary into GOBIN
make check          # tidy + vet + tests
make help           # every available target

make is preinstalled on macOS/linux, for windows get the make-X.Y.Z-without-guile-w32-bin.zip e.g. from sourceforge.net and extract make.exe to a folder in %PATH%. On a machine that already has a mingw-w64 toolchain (Qt's, for instance) it is there as mingw32-make.exe instead, and then no download is needed. The Windows builds also work without Make: build-windows.cmd / build-android.cmd are the scripts an end-to-end build uses.

Or with the Go toolchain alone:

# recommended flavour, the fastest (cgo sqlite + built-in speex), needs a C compiler
go install -tags sqlite_fts5 github.com/DMSHLabs/DictShelf@latest

There is no other flavour: cgo is the only build this fork makes. A build with no tags, or with CGO_ENABLED=0, fails on purpose (internal/store/driver_missing.go) instead of quietly linking a different driver — the pure-Go one (modernc.org/sqlite, -tags purego) was removed on 2026-11-03, so the measured index sizes and the tests always describe the binary that ships.

CI builds are generated with github actions — .github/workflows/build-cgo.yml builds the cgo flavour with the internal speex decoder and optimized sqlite3, on each platform's own runner (cgo cannot cross the host arch/OS). Supported OS's: macOS (arm64/amd64), Linux (amd64/arm64) and Windows (amd64).

More details: https://dictshelf.com/reference/building/

Building the macOS bundle from source

💡A golang environment is required. See Build from source above.

Run make mac-app-install from project root to build DictShelf.app and install it to ~/Applications (no sudo, no admin prompt):

make mac-app            # dist/DictShelf.app — universal-ready, ad-hoc signed
make mac-app-install    # copy it to ~/Applications (APP_DEST= to relocate)

The bundle is the same binary as console dictshelf which spawns no terminal window, and additionally adds a menu-bar icon with common actions. See more about running on macOS.

Acknowledgements

Almost nothing here was invented by this project. Some of the formats dictshelf reads are open-source, others are closed source, and they are available because other people spent years working on dictionaries and tools to read, write and convert data in these formats.

Prior art and format knowledge

• pyglossary — its plugins are the clearest working description of MDX/MDD, StarDict, Slob, DSL and BGL that exists anywhere, and the BGL parser in dictshelf is ported from pyglossary's babylon_bgl plugin. Thanks to @ilius and pyglossary's contributors for sustained, meticulous work on formats nobody else kept maintaining.
• GoldenDict and the actively developed fork goldendict-ng — the program that made these dictionaries worth owning, and the model for the BGL reader's streaming decompression.
• medict by Quan Chen (formerly go-mdict) — the MDX/MDD parser in internal/gomdict is derived from it.
• Raul Fernandes and Karl Grill — the original reverse engineering of the Babylon BGL format.
• slob and Aard 2 by Igor Tkach, StarDict, ABBYY Lingvo's DSL, and Kiwix's ZIM.

Libraries and components

• SQLite and its FTS5 extension — the entire prepared library: storage, headword index, and full-text search across a hundred dictionaries at once. FTS5 made this project possible.
• Public domain, and maintained at that standard for twenty-five years.
• mattn/go-sqlite3 — cgo SQLite driver; the only driver since the pure-Go one was removed in 2026-11.
• Speex — Jean-Marc Valin and the Xiph.Org Foundation. internal/speex vendors the reference decoder so .spx pronunciations play without an external tool, and it includes kiss_fft by Mark Borgerding.
• anchore/go-lzo — LZO1X decompression for MDX record blocks, written from the kernel's format documentation and lzokay by Jack Andersen.
• c0mm4nd/go-ripemd — RIPEMD, for MDX key-block decryption.
• cespare/xxhash — MDX v3 checksums.
• klauspost/compress — zstd and deflate, for ZIM clusters and Slob bins.
• ulikunitz/xz — LZMA, for Slob and ZIM content.
• aaaton/golem — English lemmatiser, so that understood finds understand.
• golang.org/x/net — HTML tokeniser, used to rewrite article markup and resolve dictionary resources.
• gogpu/systray and godbus/dbus — the tray icon, and its Linux desktop integration.
• Inno Setup by Jordan Russell — the Windows installer: small, scriptable, and free for as long as Windows has had installers.
• Go — the stack that lets us cross-compiles a static binary for eight platforms from one machine, including android.

Not affiliated with, or endorsed by, any of the above.

Licence

GPL-3.0-or-later — see LICENSE.

The files this fork authored, and its changes to the ones it inherited, are © 2026 DmShAl (Shepeta Dmitry), under the same licence; upstream's copyright notices remain in place where upstream wrote the file.

dictshelf licenses prints the full third-party notices from inside the binary; the same text is in THIRD-PARTY-NOTICES.md.

Third-party code included in this repository:

Component	Origin	License
internal/gomdict (MDX/MDD parser)	medict, © 2023 Quan Chen	GPL-3.0-or-later
internal/format/bgl (BGL parser)	ported from pyglossary's babylon_bgl	GPL-3.0-or-later
internal/speex/clib (Speex decoder)	Speex, © Jean-Marc Valin / Xiph.Org, Analog Devices	BSD-3-Clause
internal/speex/clib (kiss_fft)	kissfft, © Mark Borgerding	BSD-3-Clause

Dependencies fetched at build time keep their own licences; every one of them, with its licence text, is listed in THIRD-PARTY-NOTICES.md (regenerate with make notices).

Documentation

Overview

Command dictshelf is DictShelf's entry point - the only one.

Go names an installed binary after the last element of its package path, so the module path github.com/DMSHLabs/DictShelf makes

go install github.com/DMSHLabs/DictShelf@latest

yield the built name directly, with no second shim package (D28). Everything the program actually does lives in internal/cli.