FAQ¶

No. DictShelf listens on the loopback address 127.0.0.1 and has no account, no telemetry, no analytics or crash reporting. It connects to the internet only to download what you ask for: lemma data, or a dictionary from a link you provide. See the Privacy Policy.

Yes. Search, lookup and indexing need no network. This is also true for the Android app. Only these need the network:

• A download of lemma data. English lemma data is built in.
• An import from a link.
• An article that refers to an image, font or script at an http:// or https:// address. Most dictionaries include their resources.
• Read aloud with a voice that the browser gets from the network. The voices of the operating system need no network.

DictShelf is a shelf of dictionaries: one program that searches every dictionary you own. It is a fork of wudict (WuWeiDict, from wú wéi 無為, the classical Chinese term for effortless action) and keeps that program's dictionary formats — including wudict markdown, which is where the old name still appears — its library layout and its HTTP API.

Yes. DictShelf is free software under the GNU General Public License, version 3 or later. You can use, change and redistribute it under that licence. The source code is on GitHub. See Licence.

The licence applies to DictShelf only. Each dictionary has its own licence.

Use your own dictionary files, or get free dictionaries:

• Kiwix: Wikipedia, Wiktionary and other reference works as .zim files.
• Any link to a dictionary, wrapped as a share link - a link in a chat or a forum post works as it is, without a page of our own behind it.
• Kiwix: Wikipedia, Wiktionary and other reference works as .zim files.
• Your own dictionary: write it as a wudict markdown file in a text editor.

DictShelf reads MDict, StarDict, Aard 2, Lingvo DSL, Babylon, ZIM and DictShelf markdown: see Formats. To install the files: Add dictionaries.

~/.dmshlabs/dictshelf/
  dictshelf.toml     settings
  state.json      dictionary order, enabled dictionaries, display preferences
  groups.ini      picker groups, only created after manually edited
  style/          custom styles
  lemmas/         installed lemma data
  db/             the library; db/spxcache/ holds converted Speex audio
~/Dictionaries    the default dictionary folder

Windows and Android: Configuration → Files.

Replace the executable, or run the new installer, DictShelf.app or APK over the old one. Settings and the library are kept. Indexes built by an older version are reported as outdated and rebuilt with Rebuild or dictshelf reindex. Use Obtainium to automatically update the Android FOSS version of DictShelf.

Click the index's switch in the dictionary panel; the switch shows its size. The switches are locked when the dictionary files are gone, because the library folder is then the only copy; 🗑 Remove… still deletes it. Rescan folders lists orphans and deletes the ones you tick.

Yes, you can use DictShelf in the terminal:

dictshelf lookup -format text Oxford.mdx flight     # show definitions as plain text
dictshelf keys   ~/Dictionaries/Oxford.mdx          # list all headwords
dictshelf ingest                                    # index the dictionary folders
dictshelf clean                                     # list removable library folders

See dictshelf --help in terminal.

Command line

On Android: the app runs the same server and works offline, and looks up a word from the text selection menu of other apps. There is no iOS app.

Android app

Short answer. Both builds are compiled from the same open-source repository and provide the same search, lookup, and indexing functionality. The primary difference is how they access dictionary files.

FOSS build. Choose this build if you need unrestricted access to dictionary files in device storage. It allows you to select dictionary folders from locations of your choice, subject to Android's storage permissions and restrictions.

Google Play build. Choose this build if you prefer distribution through Google Play and automatic app updates, or if you want to avoid granting the app broad storage access. It uses Android's Storage Access Framework (SAF), which lets you grant access to specific folders without granting general access to device storage.

The Google Play build stores its app-managed dictionary data in:

/sdcard/Android/data/com.dmshlabs.dictshelf/files/Dictionaries

On recent Android versions, this directory is generally inaccessible through standard file managers. This can make it more difficult to manage or transfer dictionary files manually.

Differences.

Disk space.

• FOSS build: the dictionary files stay where you put them. One copy of each dictionary exists.
• Google Play build: an import copies the dictionary files into the app. Two copies exist until the import ends. The import does not start if the free space is less than the size of the files.
• Google Play build: after the import, the app offers to delete the originals. If you keep them, the dictionaries use two times the disk space.
• Google Play build: dictionary files in Android/data/com.dmshlabs.dictshelf/files/Dictionaries on a microSD card are read there. They use no internal storage and need no import.
• Both builds: the library adds the indexes and the media packs. It is in Android/data/com.dmshlabs.dictshelf/files/db.

Uninstall. Android deletes Android/data/com.dmshlabs.dictshelf: the library, the settings and the lemma data.

• FOSS build: Internal storage → Dictionaries stays. After a new install, the indexes are built again.
• Google Play build: the imported dictionary files are in Android/data. Android deletes them too.

Advantages of the FOSS build.

• The dictionary folder is a usual folder. A file manager or a computer can add, change and delete files in it.
• To add a dictionary, copy its files. There is no import and no second copy.
• An uninstall does not delete your dictionary files.
• Google gets no install or crash data.
• Other devices on your network can connect, for testing: Access.

Disadvantages of the Google Play build.

• Each dictionary must be imported. During the import, it needs two times its size in free space.
• Android 11 and later hide Android/data from file managers. To get the imported files, use USB (File transfer), adb pull or adb push.
• An uninstall deletes the imported dictionary files. Copy them before you uninstall.
• Google collects install and crash data: Privacy Policy.
• Other devices cannot connect.

The Google Play build has these advantages: it asks for no storage permission, and Google Play installs the updates.

Signing certificate collision. The two builds have the same package name, com.dmshlabs.dictshelf, and different signing certificates. Android does not install an update with a different certificate:

• You cannot install the two builds on one device at the same time.
• You cannot install one build over the other. Android shows an error.
• Obtainium cannot update the Google Play build. Google Play cannot update the FOSS build.

To change to the other build:

1. From Google Play to FOSS only: copy Android/data/com.dmshlabs.dictshelf/files/Dictionaries to a computer, over USB or with adb pull.
2. Uninstall the current build. Android deletes the library, the settings and the lemma data.
3. Install the other build.
4. FOSS build: put the dictionary files in Internal storage → Dictionaries. Google Play build: Import dictionaries → Choose folder.
5. Download the lemma data again. Make your settings again.

The app needs:

• Android 8.0 or later.
• A 64-bit ARM (arm64) processor. There is no build for 32-bit ARM or x86 devices.

FOSS build, other causes:

• Android blocks the APK. Allow Install unknown apps for the app that opens the APK: the browser or the file manager.
• The Google Play build is installed. Android cannot install one build over the other: see the question on the two builds above.

Set SERVER_IP to 0.0.0.0. Requests from the network then need the access key (AUTH): dictshelf token prints a link that carries it; open it once in the browser on the other device. Deleting dictionaries from another device also needs ALLOW_REMOTE_DELETE.

No. Indexes go into the library. A replacement for a broken resource goes into the dictionary's library folder as a resource override. Only 🗑 Remove… and dictshelf rm delete dictionary files.

Yes, from the command line. dictshelf dump can export a dictionary as CSV or as wudict markdown:

dictshelf dump -o ~/exports ~/Dictionaries/Oxford.mdx              # CSV
dictshelf dump -format md -o ~/exports ~/Dictionaries/Oxford.mdx   # wudict markdown

For more details see: dictshelf dump --help

The images, audio and other resources are exported to a folder next to the output. The CSV is compatible with pyglossary, and thus can be converted to other formats, such as StarDict. See DictShelf dump.

The Android app has no command line, but it is possible to build and run the desktop version of DictShelf on Android in the Termux environment. See Can I use DictShelf in Termux? below.

Yes, you can build DictShelf from the source code in Termux. The server and all commands work, as on a desktop.

1. Install Termux from F-Droid or from GitHub.

2. Install the build tools:

   pkg upgrade
   pkg install golang clang git make
   

   go version must show 1.26.5 or later.

3. Get the source code and build DictShelf:

   git clone https://github.com/DMSHLabs/DictShelf
   cd dictshelf
   make build                            # cgo: fast SQLite, built-in Speex decoder
   install -m 755 dictshelf $PREFIX/bin/
   

   The first build compiles SQLite. This can take some minutes.

   Without clang there is no build at all: make build compiles SQLite and needs a C compiler. Install clang (or gcc) in Termux first.

4. Give Termux access to the shared storage:

   termux-setup-storage
   

   Internal storage is then ~/storage/shared.

5. Write the settings:

   mkdir -p ~/.dmshlabs/dictshelf
   cat >> ~/.dmshlabs/dictshelf/dictshelf.toml <<'EOF'
   DICT_DIR    = "~/storage/shared/Dictionaries"
   SERVER_PORT = "6889"
   NO_BROWSER  = "1"
   EOF
   

   ~/storage/shared/Dictionaries is also the folder of the DictShelf FOSS build. The two use the same dictionary files. Each has its own library. The DictShelf app uses port 6888, so DictShelf in Termux uses 6889.

6. Start the server:

   dictshelf
   

7. Open http://127.0.0.1:6889 in a browser on the phone.

8. To keep the server running when the screen is off:

   termux-wake-lock
   

To update: in the dictshelf folder, run git pull, make build and the install command again.

Yes. All dictionaries in the dictionary picker searches every enabled dictionary.

• To remove a dictionary from All dictionaries, clear its checkbox in the dictionary panel.
• To search one dictionary, choose it in the picker.
• To search a set of dictionaries, choose a group in the picker: a language, a language pair, or your own group.
• To change the order of the results, drag ⠿ in the dictionary panel.

See Picker groups and Dictionary panel.

Yes.

• Theme: ◐ chooses auto, light or dark.
• Text size: ☰ → − 15px +.
• Your own CSS: ☰ → folder summary → Custom styles…. App changes the DictShelf page. Article changes every dictionary article. Examples… inserts ready styles, such as sepia, true black, a serif font, and a compact layout for phones. Files adds fonts and images.
• One dictionary only: a resource override.

If a rule hides the page, open http://127.0.0.1:6888/?style=off. See Custom styles.

Spanish lemma data is not installed, or DictShelf cannot tell that the dictionary is Spanish.

Install it: ☰ → folder summary → Lemmatization… → tick Spanish. It applies from the next search. In a terminal: dictshelf lemmas download es.

Most .mdx and .slob dictionaries do not declare their language. Name the file with a language code first (es-en-collins.mdx), or put it in a folder named by the code (es/). English is assumed when nothing else is found. See language detection.

No. There used to be one — a second SQLite driver written in Go — and it was removed in November 2026: it was a different binary with different measured index sizes, and every build this project makes already used cgo. A build without cgo now fails on purpose instead of quietly using another driver, and the -purego artifacts and tags are gone. See One build.

dictshelf --no-browser, or NO_BROWSER = "1" in ~/.dmshlabs/dictshelf/dictshelf.toml.

With Zensical, which needs Python 3:

cd pages
pip install zensical
zensical serve      # localhost:8000, rebuilt on change
zensical build      # static HTML in pages/site