Spell-check Files Safely with Aspell on the Command Line

Aspell can fix a document interactively, list misspellings for a script, or feed suggestions to another tool. Picking the wrong mode is the usual mistake, so this guide covers all three, plus getting British English consistently instead of whatever the locale picks. The examples use Aspell 0.60.8.1 from Debian package aspell 0.60.8.1-1build1. Allow about ten minutes, plus time to review any suggested replacements.

This assumes the aspell command and an English dictionary are installed, and it uses only ordinary user privileges throughout. Do not run the checker with sudo: spelling a document should never need elevated access, and running it as root can leave root-owned configuration or word-list files behind.

1. Check the installed command and dictionary

Confirm which executable will run and which version it reports:

$ command -v aspell
/usr/bin/aspell
$ aspell --version
@(#) International Ispell Version 3.1.20 (but really Aspell 0.60.8.1)
aspell 0.60.8.1-1build1

Aspell's library holds no word lists on its own. Ask the installed utility which dictionaries it can actually use:

$ aspell dicts
en
en_GB
en_US
...

The exact list depends on the dictionary packages you have installed. If en_GB is missing, do not quietly substitute another variety when British spelling matters: install the matching dictionary through your normal package process, then repeat this check.

2. Check a copy interactively

check opens an interactive correction session for one file. Make a copy first if the source is valuable or tracked in version control:

$ cp -- /path/to/report.txt /tmp/report-to-check.txt
$ aspell --lang=en_GB check /tmp/report-to-check.txt

Aspell steps through suspected words and offers replacement choices. The key mapping is interactive, so read the prompt your installed version actually shows rather than guessing a response. Save the corrected copy only once you have reviewed each proposed change.

$ diff -u -- /path/to/report.txt /tmp/report-to-check.txt

Aspell can create a .bak copy when it makes changes and backup mode is on. That is useful, but not a reason to overwrite an original blindly: the shell redirection examples later in this guide carry their own truncation risk too.

3. List misspellings without changing the file

For a report, a pipeline, or an automated check, use list. It reads text from standard input and writes one word per line for anything it does not recognise:

$ printf '%s\n' 'This sentense has a mispelled wurd.' | aspell --lang=en_GB list
sentense
mispelled
wurd

• It never rewrites the input. Good for a build check, but the output is just a list of candidate words.
• Names and technical terms may be missing from the dictionary. Review candidates in context before touching the document.

$ printf '%s\n' 'A clean sentence.' | aspell --lang=en_GB list > /tmp/aspell-misspellings.txt
$ status=$?
$ printf 'aspell list status: %s\n' "$status"
aspell list status: 0

An empty output file is not proof the prose is perfect. It only means this dictionary and configuration reported nothing.

4. Use pipe mode when another program needs suggestions

pipe speaks the ispell -a compatibility protocol: a status line for each input word, followed by suggestions when a word is unknown:

$ printf '%s\n' 'helo' | aspell --lang=en_GB pipe
@(#) International Ispell Version 3.1.20 (but really Aspell 0.60.8.1)
& helo 23 0: hello, helot, help, halo, hell, heal, heel, held, helm, hero, he'll, Hal, Hale, hale, hole, Hall, Hill, Hull, hall, hill, holy, hula, hull

This protocol is for editor integrations and other programs, not casual parsing with a single regular expression. A leading & marks a misspelling with suggestions attached; a line containing only * means the word was accepted. Test any integration you build against the exact protocol your deployed version emits.

5. Select language and filter deliberately

Aspell's language defaults from the current locale, which means the same command can behave differently on two machines. Put the choice in the command itself when reproducibility matters:

$ aspell --lang=en_GB list < README.txt
$ aspell --lang=en_US list < README.txt

The language name follows the documented locale-style pattern: a two-letter language code with an optional country code, so en_GB and en_US can flag different spellings. Choose the dictionary that matches the document, not the location of the server.

For structured input, pick a filter mode so markup gets treated as markup. The manual documents --mode=html, --mode=tex and --mode=nroff:

$ aspell --lang=en_GB --mode=html list < page.html
$ aspell --lang=en_GB --mode=nroff list < manual.nroff

Check the result on a small sample before applying a filter to a large collection. A filter changes what Aspell sees; it does not validate that the surrounding document is syntactically correct.

6. Inspect configuration before changing it

When a result surprises you, query the active values instead of guessing which file supplied them:

$ aspell config lang
en_US
$ aspell config personal
/home/you/.aspell.en_US.pws
$ aspell config
...

The manual describes a global file, normally /etc/aspell.conf, and a per-user file, normally ~/.aspell.conf. Command-line options and environment settings override both. Reach for --conf=FILE or --per-conf=FILE only when you have a specific file to test.

Configuration lines use an option name followed by a space and its value, not an equals sign: lang en_GB is the documented form. Do not edit a global file just to fix one invocation. Use --lang=en_GB while you diagnose the result, then make a deliberate per-user change if you genuinely want a lasting default.

Common traps

• No dictionary. aspell dicts shows what is available. Install a dictionary package rather than inventing a name.
• Unexpected spelling variety. The locale may have picked a different language. Pass --lang explicitly and check it with aspell config lang.
• Lost output. > truncates its destination before the command runs. Write to a temporary path, check it, then mv it into place only after review.
• False positives. Technical names and project vocabulary are not always dictionary words. Do not add every candidate to a personal list without checking its spelling and scope first.
• Interactive command in automation. Use list for a simple candidate report, or implement the documented pipe protocol. check expects a terminal and a person making decisions.