Spell-Check a File from the Shell with enchant-2

Run enchant-2 -l over a text file and get back nothing but the misspelt words, one per line, with the file left untouched. The examples use Enchant 2.3.3 from Debian package enchant-2, version 2.3.3-2build2. Allow about ten minutes. You need a shell, a readable text file and at least one working Enchant dictionary provider.

There is one wrinkle on the test machine: the Enchant providers are installed, but no usable dictionary is configured for the C.UTF-8 locale. Step 4 shows how to spot that condition. This guide does not pretend a spell-check result exists when the dictionary setup is incomplete.

1. Check the installed command

Start with the binary and package version. These are read-only commands and need no elevated privileges:

$ command -v enchant-2
/usr/bin/enchant-2
$ dpkg-query -W -f='${Package} ${Version}\n' enchant-2
enchant-2 2.3.3-2build2
$ enchant-2 -v
@(#) International Ispell Version 3.1.20 (but really Enchant 2.3.3)

enchant-2 is an ispell-compatible command. It has two useful modes:

• -l lists only the misspellings.
• -a gives suggestions in ispell pipe mode.

It reads the file named at the end of the command, or standard input when you name none.

2. Check a file without modifying it

Create or choose a plain text file you are happy to read. The command only reads the input file and prints its result. It does not rewrite the file:

$ printf '%s\n' 'This line contains a mispeled word.' > /tmp/enchant-example.txt
$ enchant-2 -l /tmp/enchant-example.txt
mispeled

That is the shape you get when a dictionary is available: one misspelt word per line. The exact list depends on the selected language, provider and installed dictionary. A clean file normally prints nothing, so check the exit status separately when scripting:

$ enchant-2 -l /tmp/enchant-example.txt > /tmp/enchant-errors.txt
$ status=$?
$ printf 'enchant-2 status: %s\n' "$status"
enchant-2 status: 0

Status 0 means the check completed. It does not claim that every word was correct. A missing input file is different: the installed command prints an error and returns status 1.

3. Add line numbers to long files

Use -L with -l when you need to find a misspelling in an editor or a review:

$ enchant-2 -L -l /path/to/document.txt

The command adds line numbers to its report. The exact separators are part of the installed command's output, so capture a real result before writing a parser.

4. Diagnose a missing dictionary

If Enchant reports Couldn't create a dictionary, the command is fine but no provider can create a dictionary for the active language. Confirm the available providers with the companion command:

$ enchant-lsmod-2
aspell (Aspell Provider)
hspell (Hspell Provider)
hunspell (Hunspell Provider)

This lists providers, not necessarily installed word lists. On the test machine enchant-2 -l still fails, because the providers cannot find a dictionary for C.UTF-8. A full provider list does not prove spell-checking is ready.

Install a dictionary through your operating system, then retry the same read-only check. The package name varies by distribution and language. Do not use sudo unless your package manager requires it, and do not run the checker as root just to hide a dictionary or permission problem.

$ enchant-2 -l /path/to/document.txt
$ printf 'status: %s\n' "$?"
status: 0

5. Choose a dictionary and provider on purpose

-d DICTIONARY selects the language dictionary, using a tag your installation supports. Check the tag against what your host actually has rather than guessing:

$ enchant-2 -d en_GB -l /path/to/document.txt

On a host with an en_GB dictionary, this prints that dictionary's misspellings. On the test machine it hits the same dictionary-creation failure as above, because no usable word list is installed. A language tag is a request, not proof that the dictionary exists.

Provider order is controlled by enchant.ordering. The per-user file takes precedence over the global one. On a typical Linux installation the user file is ~/.config/enchant/enchant.ordering, and the environment variable ENCHANT_CONFIG_DIR can point at another configuration directory. The installed manual gives entries such as:

*:aspell,hunspell,nuspell
en:aspell,hunspell,nuspell
en_GB:hunspell,nuspell,aspell

Each line maps a BCP 47 language tag to a comma-separated provider order. The * entry is the fallback for languages without a more specific line.

6. Use a personal word list carefully

-p WORDLIST supplies a personal word list for a check. Keep the file under your own account and review entries before adding project names, usernames or other sensitive terms. A personal list is no substitute for choosing the right language:

$ printf '%s\n' 'Alice' > /tmp/enchant-personal.txt
$ enchant-2 -d en_GB -p /tmp/enchant-personal.txt -l /path/to/document.txt

The manual documents -p, although its compact synopsis leaves it out. The installed help output confirms it accepts a word-list file. If the word list is wrong, remove the temporary file rather than overwriting a real personal dictionary:

$ rm -- /tmp/enchant-personal.txt

7. Use pipe mode only when a program needs it

-a emits an ispell-compatible protocol with suggestions and status markers. It is meant for an editor or wrapper that speaks that protocol, not for a human-readable report:

$ enchant-2 -a /path/to/document.txt

Suggestion order and exact spacing depend on the provider. For a shell report, prefer -l and add -L if locations matter. Do not parse the output of -a as though it were a stable JSON or CSV format.