Hunspell: the spellchecking library behind LibreOffice, Firefox and Chrome

What Hunspell solves, and who actually needs it

Spell checking looks trivial until you leave English. A word list with a hash table handles "cat" and "cats", but it collapses on Hungarian, Turkish, Finnish or Azeri, where a single stem can take dozens of inflectional and derivational forms. Hunspell's answer is a dictionary plus an affix file: the .dic holds stems, the .aff holds rules that generate and recognise the rest. The README describes the design as handling "dictionary and affix homonyms", twofold affix stripping, and 64 thousand affix classes with an arbitrary number of affixes. That is the actual selling point, not the word list.

The audience is narrow and specific. Application developers who need to embed checking in an editor, an office suite plugin, a browser, or a document pipeline. The README lists LibreOffice, Mozilla Firefox, Google Chrome, Linux distributions and macOS as users, which tells you the library is proven at scale in exactly that role. It is also a command-line tool with an Ispell-like terminal interface, so it fits shell pipelines and batch jobs as well as embedded use. If your requirement is "check English prose in a web form", you are paying for morphology you will never exercise.

The affix and dictionary mechanism, and what the C++ API exposes

The data flow is straightforward once you see it. A language is a pair of files: an affix file describing rules, and a dictionary file listing stems with flags that point at those rules. Hunspell reads both, builds its internal representation, and then answers three different questions from the same structure: is this word correct, what are the likely corrections, and what is the stem or morphological analysis of this form. The README calls out stemming and morphological analysis, generation, and a SPELLML XML API layered over the plain spell() function so that stemming, generation and custom dictionaries can be reached through one call.

The command-line tool adds a second layer: parsing formats for text, OpenDocument, TeX/LaTeX, HTML/SGML/XML and nroff/troff, so it can check a document without you stripping markup first. It also supports multiple dictionaries at once, which the README illustrates with hunspell -d en_US,de_DE,de_medical. That multi-dictionary flag is more useful than it sounds: a medical dictionary layered over a general one lets you accept domain vocabulary without polluting the base list.

The API surface is C++/C plus a shared library, with bindings for other languages. The README does not enumerate the bindings, so if you are working in Python, R or Emacs, treat the binding as a separate dependency with its own release cadence. The core library and the wrapper are not the same project.

Installing Hunspell from source on Linux and macOS

The README gives the build steps directly; there is no separate install guide. On Ubuntu the build dependencies are four packages, and the configure step follows. Run these in the repository root:

sudo apt install autoconf automake autopoint libtool

Then configure, build and install. The README notes that on Linux gettext and libiconv are part of the standard library, so you do not install them separately:

autoreconf -vfi
./configure
make
sudo make install
sudo ldconfig

If you cannot or will not install system-wide, the README offers a DESTDIR form that also skips ldconfig because libtool is not installing into the system prefix:

make install DESTDIR="$HOME/hunspell-root"

On macOS the README is explicit that you must use clang rather than g++, because Homebrew dependencies are built with clang. Install the tooling with brew, then run the same autoreconf and configure sequence. Two configure flags matter for anything beyond the library: --with-warnings for dictionary development, and --with-ui for the interactive terminal interface, which additionally needs ncurses and optionally readline. Without --with-ui you get the library and the tool but not the Ispell-like interactive screen.

A first real use: checking a file and getting a stem

Once installed, the tool needs a dictionary. The README does not ship one in the repository tree; dictionaries come from the language-specific projects that publish .aff and .dic pairs. Assuming you have an en_US pair available, checking a file is a single invocation, and the tool prints misspelled words with suggestions. The README documents multiple dictionaries through the -d flag:

hunspell -d en_US,de_DE,de_medical

For programmatic use, the interesting options are stemming and morphological analysis, documented as -s and -m. Pointing -s at a word list gives you the stem for each form, which is the feature that distinguishes Hunspell from a plain word-list checker. The README lists these as morphological analysis (option -m) and stemming (option -s).

To see what the tool can do before writing any code, the README points at hunspell -h for the option summary, man hunspell for the tool, man 3 hunspell for the library API, and man 5 hunspell for the dictionary format. The man 5 page is the one to read if you intend to write or modify an affix file; the format is where most of the real complexity lives.

Where Hunspell is the wrong tool

The build is the first wall. There is no packaged binary in the repository, no installer, and no single-command setup. You need autoconf, automake, autopoint and libtool before you can even run configure. On Windows the README describes two routes, MSYS2 with mingw-w64 and Cygwin, and both are heavier than a typical dependency. The MSYS2 package list includes mingw-w64-x86_64-libiconv, and the README states plainly that without it the build still succeeds but the tool cannot convert between dictionary encodings, so any dictionary declaring a non-UTF-8 SET such as ISO8859-1, ISO8859-2 or ISO8859-15 fails at runtime. That is a silent-at-build, loud-at-run failure mode, and it is easy to ship by accident.

Second, Hunspell checks spelling and morphology. It does not check grammar, style or sentence structure. If your requirement is "this sentence is awkward" or "this comma is wrong", Hunspell will return a clean result and you will conclude the text is fine. That is a different class of tool.

Third, dictionary quality is not Hunspell's responsibility. The engine is only as good as the .aff and .dic files you load, and those come from separate projects with separate maintenance. A missing or stale dictionary for your language produces wrong results that look like engine bugs. The repository does not bundle dictionaries, so this is a dependency you own.

Hunspell compared with Aspell and MySpell

MySpell is not really an alternative; it is the ancestor. The README states that Hunspell's code base comes from OpenOffice.org's MySpell library, originally a C++ reimplementation of Ispell's spell checking and affixation, later extended with n-gram suggestions. Choosing MySpell over Hunspell means choosing the earlier, less capable version of the same lineage. The practical difference is the morphology work: compound handling, twofold affix stripping, conditional affixes and the language-specific casing rules for Azeri, Turkish and German sharp s are Hunspell additions.

Aspell is the more genuine comparison, and the difference is in the dictionary model. Aspell is a separate codebase with its own dictionary format and its own affix handling. Hunspell's format is the one LibreOffice, Firefox and Chrome consume, which means the ecosystem of published .aff and .dic pairs is built around Hunspell's rules. If your application already interacts with those dictionaries, or you want the same dictionary files the browsers use, Hunspell is the format you need to read. If you are starting fresh and only need English, Aspell's packaging story is often simpler, and that simplicity is a real advantage when you do not need compounding or rich morphology.

Maintenance, licensing and what an upgrade costs

The repository is not archived and was last pushed on 2026-09-19, so it is under current development. The release history is worth reading before you plan an upgrade: v1.7.3 was tagged on 2026-05-05, and the previous release, v1.7.2, dates to 2022-12-29. That is a gap of more than three years between releases. A long gap does not mean the project is dead, but it does mean you should not assume frequent point releases with incremental fixes. Plan to track the master branch or pin a tag and carry patches yourself.

Licensing needs care rather than optimism. The README says LGPL/GPL/MPL tri-license, and the repository root contains COPYING, COPYING.LESSER and COPYING.MPL alongside license.hunspell and license.myspell. The myspell license file is separate because the code base descends from MySpell, so the provenance is not a single uniform grant. If you are linking the library into a proprietary product, read all of those files with your own counsel; this article is not legal advice and the presence of three license files means the answer is not obvious from the repository description alone.

Editorial conclusion

Adopt Hunspell if you need a spell checker with real morphology support for languages such as Hungarian, Turkish or German compounding, and you are willing to build from source or use a language binding. Do not adopt it if you only need English suggestions and want a drop-in service with no dictionary files to manage; a hosted checker or a simpler engine will cost you less. Before committing, verify that an .aff and .dic pair exists for every language you ship, check whether your build needs libiconv for non-UTF-8 dictionaries, and run make check on your target platform.

Frequently asked questions

Official sources

1. hunspell/hunspell on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases