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.
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-1build1Aspell'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.
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.txtAspell 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.
Checkpoint: after the session, inspect the copy and compare it against the original.
$ diff -u -- /path/to/report.txt /tmp/report-to-check.txtAspell 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.
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
wurdCheckpoint: capture the exit status immediately if a script depends on it.
$ 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: 0An empty output file is not proof the prose is perfect. It only means this dictionary and configuration reported nothing.
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, hullThis 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.
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.txtThe 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.nroffCheck 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.
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.
aspell dicts shows what is available. Install a dictionary package rather than inventing a name.--lang explicitly and check it with aspell config lang.> truncates its destination before the command runs. Write to a temporary path, check it, then mv it into place only after review.list for a simple candidate report, or implement the documented pipe protocol. check expects a terminal and a person making decisions.aspell --version and aspell dicts identify the installed utility and usable dictionary.diff -u was used before accepting them.list or the documented pipe protocol rather than trying to drive the interactive checker.