Rebuild Ispell Hash Files Safely with ispell-autobuildhash

A dictionary package upgrade can leave a stale Ispell hash behind, and ispell-autobuildhash is what rebuilds it. This guide shows you how to check whether it has work to do, preview that work, and run a rebuild only when the installed dictionary setup actually needs it. The command is part of dictionaries-common, installed here as version 1.29.7. Allow about ten minutes for a check, or longer if you are investigating a package upgrade.

This guide is for an administrator or package maintainer who already has an Ispell dictionary package installed. Ordinary checks do not need elevated privileges. A real rebuild can write below /var/lib/ispell and depends on dictionary package files, so use the account and privilege model normally used for package maintenance.

1. Check the installed tool

Confirm the executable and package version before relying on its behaviour. These are read-only checks:

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

The local manual page is dated 7 September 2023 and identifies the script as version 1.29.7. It is meant to be called by the dictionaries-common tools and package maintainer scripts, not run against arbitrary dictionaries: it only considers packages prepared to use this mechanism.

2. Preview the normal decision

Run the dry-run mode first. It reports what would be done without making the real change:

$ ispell-autobuildhash --dry-run
$ printf 'exit status: %s\n' "$?"
exit status: 0

On this machine the command exits successfully and prints nothing because there is no usable Ispell compatibility information. That is a no-op, not proof that every possible dictionary is current. The script compares a dictionary's /var/lib/ispell/<dict>.compat value with /usr/share/ispell/ispell.compat, and can fall back to the upstream version from the first line of ispell -vv when that file is absent.

Checkpoint: If you expected a rebuild, inspect the inputs without editing them.

$ ls -l /var/lib/ispell /usr/share/ispell /usr/lib/ispell
$ test -r /usr/share/ispell/ispell.compat && cat /usr/share/ispell/ispell.compat
$ find /var/lib/ispell -maxdepth 1 -type f -name '*.compat' -print

File names and dictionary names are host-specific. Do not create a compatibility file merely to make the command produce output.

3. Understand when a hash gets rebuilt

These paths describe the package contract, not a repair recipe. Do not hand-edit a hash file or replace a package-owned symlink while diagnosing a no-op. A missing source or malformed package should be fixed through the dictionary package.

4. Force a rebuild only after the preview

--force skips the compatibility comparison and requests a rebuild for every compatible dictionary the script finds. Preview that broader action first:

$ ispell-autobuildhash --force --dry-run
$ printf 'exit status: %s\n' "$?"
exit status: 0

If the preview identifies a dictionary that needs repair, run the real command with the same environment and the privileges required to update the package-owned paths:

$ sudo ispell-autobuildhash --force
$ printf 'exit status: %s\n' "$?"
exit status: 0

Warning: do not use --force as a routine health check. It can rebuild every compatible dictionary, which consumes more time and changes generated files, and there is no general undo option. Recovery is to rerun the package's normal maintainer operation after correcting the source package, or reinstall the affected dictionary package through the system package manager.

5. Use debug output when the decision is unclear

Add --debug to ask the script for extra information. Combine it with dry-run while investigating:

$ ispell-autobuildhash --debug --dry-run
ispell-autobuildhash: Using temporary directory "/tmp/ispell-auto.XXXXXX"
ispell-autobuildhash: no ispell compat info. ispell may not be installed. Aborting ...

The final temporary-directory suffix is generated at runtime, so your output will differ. The wording above is the useful diagnostic from this installation. Despite the word "Aborting", this no-work case returned status 0 here. Read both the message and the exit status; do not treat a quiet successful run as a failed rebuild.

--triggered is for the package trigger stage. Under dpkg, it stops the script trying to set its own trigger and runs the real autobuild code straight away. Run outside dpkg, the option has no practical effect, and it is not needed for an administrator's normal manual check.

6. Keep package ownership and service impact clear

This script manages dictionary hash files, not a running daemon. A rebuild should not require restarting a service, but programs using a dictionary may pick up the new hash on their next invocation. Keep the source .aff and .mwl.gz files in place until verification is complete.

For package maintainers, the manual also requires resetting the compat file on every new install or upgrade, and removing both the compat file and generated hash on package removal. The auto-compat field in a dictionary's <dict>.info-ispell file can help installdeb-ispell add the required debhelper snippets. Review generated maintainer scripts before shipping a package.

Done means