Safely Rebuild Aspell Hash Files with aspell-autobuildhash

aspell-autobuildhash rebuilds Aspell's binary dictionaries, but only when a compatibility marker says they are actually stale. Knowing that marker saves you from forcing a rebuild you did not need. You will learn to inspect the compatibility state, preview a rebuild, run it for real, and know when --force is actually justified.

Allow about fifteen minutes, plus dictionary rebuild time on a slower machine. You need a shell, the dictionaries-common package and a supported Aspell dictionary. This guide uses the installed Ubuntu package versions here: dictionaries-common 1.29.7 and aspell 0.60.8.1-1build1. Inspection can be unprivileged, but the command writes under system directories, so a real run needs root.

1. Check the installed command

Confirm the command comes from the package you expect. This is read-only and needs no elevated privileges:

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

The installed manpage is dated 7 September 2023 and identifies the script as version 1.29.7. Package versions and output vary between distributions, so keep the version alongside any incident notes or deployment record.

There is no conventional --help option. The documented flags are --debug, --dry-run, --force and --triggered. Do not borrow switches from another dictionary tool: they will not apply here.

2. Inspect the compatibility state

The rebuild decision comes from compatibility markers, not from whether an .rws file simply exists. The Aspell compatibility value lives at /usr/share/aspell/aspell.compat; for each supported dictionary, /var/lib/aspell/<lang>.compat records the value used by its last successful build.

Replace LANG with the dictionary basename you actually use. Reading these files is ordinary, unprivileged inspection:

$ LANG='en'
$ printf 'Aspell compatibility: '
$ cat /usr/share/aspell/aspell.compat
$ printf '%s compatibility: ' "$LANG"
$ cat "/var/lib/aspell/$LANG.compat"
$ ls -l "/var/lib/ispell/$LANG.rws" "/usr/lib/aspell/$LANG.rws"

Checkpoint: if the compat file is missing, do not create one by hand just to quiet the command. A package maintainer normally creates or resets it during install or upgrade, so check the dictionary package's files and maintainer scripts first.

3. Preview the normal rebuild decision

Run --dry-run before a real run. It reports what would happen without doing it. Root is still required, because the script operates on package-managed state:

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

Output is host-specific. A clean system, like this one, may print nothing and still return status 0. A machine with stale or reset compatibility markers may list dictionaries that would be rebuilt. Treat a non-zero status as a failed preview, not as permission to add --force.

Checkpoint: record the preview output and status. If the command says it must run as root, rerun the same preview with sudo. If sudo is unavailable, ask an administrator to run the preview; do not change ownership or permissions on the dictionary directories yourself.

4. Run the compatibility-aware rebuild

Once the preview matches what you expect, run the command without --dry-run:

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

This script is meant to be called by the dictionaries-common tools during package installation and upgrade processing. A successful status means the script completed; it does not mean every installed dictionary was rebuilt. Dictionaries with matching compatibility levels are left alone, and unsupported packages are ignored.

After a successful run, check the marker and generated file for the dictionary you care about:

$ cat /var/lib/aspell/en.compat
$ ls -lh /var/lib/ispell/en*.rws

The generated hash lives under /var/lib/ispell, and a dictionary package should expose it through a matching symlink in /usr/lib/aspell. Do not replace that symlink with a copied file: package upgrades rely on the documented layout.

5. Use force only for a deliberate repair

--force skips the compatibility comparison and rebuilds the hash for every dictionary that provides a compat file. It is useful after a suspected stale or damaged hash, but it is slower and regenerates more system files than a normal run:

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

Run the forced command only after reviewing the dry-run output, and arrange a maintenance window if the host serves applications that load these dictionaries. It is not a generic fix for a missing dictionary, a broken symlink or an unsupported package: those are separate packaging or filesystem problems.

Warning: there is no general undo for a forced rebuild. Recovery means reinstalling or reconfiguring the affected dictionary package and letting its maintainer scripts recreate the expected compat marker, hash and symlink. Save package metadata and the current marker values before forcing a repair, and never edit generated hash files while the package manager is running.

6. Investigate failures without guessing

Reach for --debug when the normal output does not explain a failure. It adds internal detail and also enables Aspell affix validation, so expect extra diagnostics:

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

Keep the exact error, the package versions and the affected language name, then check these boundaries:

The script accepts --triggered for the package trigger stage. Under dpkg control, it avoids setting the same trigger again while running the real code. Run the script by hand outside dpkg and the manpage says the option has no practical effect, so leave it out of manual repair commands unless you are deliberately reproducing package-trigger behaviour for a maintainer investigation.

Done means