Rebuild Wordlist Links with update-default-wordlist

A wordlist package installs or gets removed, and update-default-wordlist is the tool that fixes the stale symlink left behind.

This guide covers update-default-wordlist on a Debian system using dictionaries-common. You will identify the installed version, inspect the current wordlist state, and, if you have a specific administrative reason, rebuild the wordlist database with the right link behaviour. Allow about 10 minutes.

The command changes system state and is normally meant for package maintenance, so do not run it as a casual refresh.

1. Check the installed package and command

Start without changing anything. The package version matters because this guide describes the locally installed 1.29.7 interface. The command normally lives in /usr/sbin, which may not be in an ordinary user's PATH.

$ dpkg-query -W -f='${Package} ${Version}\n' dictionaries-common
dictionaries-common 1.29.7
$ command -v update-default-wordlist
/usr/sbin/update-default-wordlist

Your version and path may differ. If the package is not installed, stop here: installing a wordlist package is a separate job, outside what this command does.

2. Understand what the command changes

The script rebuilds /var/cache/dictionaries-common/wordlist.db from registration data below /var/lib/dictionaries-common/wordlist. It also reads the debconf value for the default wordlist and, unless manual mode or an option stops it, sets default symlinks below /etc/dictionaries-common pointing into /usr/share/dict.

So it is not a read-only status check. It can alter a cache, debconf-related state, and symlinks that programs rely on for the conventional dictionary paths. The installed manpage explicitly warns against running it from the command line unless you know why.

Checkpoint: If you only want to pick a wordlist interactively, use the package's selection workflow instead. This script is chiefly called by a wordlist package's post-installation step, by select-default-wordlist, or by the dictionaries-common post-installation process.

3. Record the current state

Before any privileged command, capture the files and links that could be affected. These are ordinary commands and do not modify the system.

$ ls -l /var/cache/dictionaries-common/wordlist.db
-rw-r--r-- 1 root root ... /var/cache/dictionaries-common/wordlist.db
$ find /var/lib/dictionaries-common/wordlist -maxdepth 1 -type f -printf '%f\n' | sort
$ find /etc/dictionaries-common -maxdepth 1 -type l -printf '%f -> %l\n' | sort
words -> /usr/share/dict/american-english

Do not treat the sample names as universal. A machine can have no registered wordlists, several packages, manual mode, or a different selected default. Save the output in your change record if the host matters.

4. Choose the narrowest supported mode

Version 1.29.7's synopsis has two options. --skip-symlinks tells the script not to try setting links in /etc/dictionaries-common. It still does the database and default-processing work, so it is not a dry run: use it when another package operation needs the registration database refreshed but link ownership has to stay untouched.

--triggered tells the script to run the full code instead of trying to enable the update-default-wordlist dpkg trigger. The manpage's prose mentions a --trigger option, but the installed synopsis and script accept --triggered. Do not substitute the singular spelling.

If you need both properties, the command is:

$ sudo /usr/sbin/update-default-wordlist --skip-symlinks --triggered

Privilege boundary: sudo is required because the command reads and writes root-owned package state. Confirm the exact host and options before entering your password: there is no general undo switch, and the command keeps no backup of the old cache or symlink choices.

5. Run it only for a known maintenance reason

For a normal package-maintenance repair where the selected default and links should be reconciled, omit --skip-symlinks but keep --triggered when you are deliberately running the complete operation outside dpkg:

$ sudo /usr/sbin/update-default-wordlist --triggered
$ printf 'exit status: %s\n' "$?"
exit status: 0

Success normally produces little or no standard output. An exit status of zero means the process completed; it does not prove a particular wordlist was selected or that every expected link exists. Debug messages may go to standard error, especially when the script clears its package-maintenance flag or reports the debconf selection.

Never pass undocumented options. The installed script also accepts an internal compatibility option named --rebuild, but the manpage does not document it and says the database is always rebuilt anyway. Stick to the documented interface.

6. Verify the result

Check the cache timestamp and inspect the links after the command. The exact link set depends on installed wordlist packages and the debconf selection, so verify names rather than copying an example blindly.

$ stat -c '%y %n' /var/cache/dictionaries-common/wordlist.db
2026-09-27 12:34:56.000000000 +0000 /var/cache/dictionaries-common/wordlist.db
$ find /etc/dictionaries-common -maxdepth 1 -type l -printf '%f -> %l\n' | sort
words -> /usr/share/dict/american-english
$ readlink -f /etc/dictionaries-common/words
/usr/share/dict/american-english

If you used --skip-symlinks, the links should not have been deliberately reset by this invocation. Compare them with the recorded pre-change output. If the cache did not update, inspect the command's error output and the ownership and contents of /var/lib/dictionaries-common/wordlist before trying again.

7. Recover from an unwanted selection

Stop if the default link now points to an unexpected wordlist, or if package tools report an invalid debconf value. Do not guess a replacement file from its name. List the installed candidates first and read the selection tool's own documentation. Correct the selected default through the supported dictionaries-common workflow, then let that workflow or the relevant package post-installation action rebuild the state.

If you changed only links and have an approved previous target, restoring a link is a separate privileged change that should follow your system's package-management policy. Record the old target before removing anything, and do not delete files under /usr/share/dict: the command manages references, not the wordlist package's data.

Done means