Skip to main content

A wrapper on hunspell for use in Python

Project description

Build Status PyPI version PyPI pyversions License: MIT


Cython wrapper on Hunspell Dictionary


This repository provides a wrapper on Hunspell to be used natively in Python. The module uses cython to link between the C++ and Python code, with some additional features. There's very little Python overhead as all the heavy lifting is done on the C++ side of the module interface, which gives optimal performance.

The hunspell library will cache any corrections, you can use persistent caching by adding the use_disk_cache argument to a Hunspell constructor. Otherwise it uses in-memory caching.


For the simplest install simply run:

pip install cyhunspell

This will install the hunspell 1.7.0 C++ bindings on your behalf for your platform.


cacheman -- for (optionally asynchronous) persistent caching

Non-Python Dependencies


The library installs hunspell version 1.7.0. As new version of hunspell become available this library will provide new versions to match.


Spell checking & spell suggestions

How to use

Below are some simple examples for how to use the repository.

Creating a Hunspell object

from hunspell import Hunspell
h = Hunspell()

You now have a usable hunspell object that can make basic queries for you.

h.spell('test') # True


It's a simple task to ask if a particular word is in the dictionary.

h.spell('correct') # True
h.spell('incorect') # False

This will only ever return True or False, and won't give suggestions about why it might be wrong. It also depends on your choice of dictionary.


If you want to get a suggestion from Hunspell, it can provide a corrected label given a basestring input.

h.suggest('incorect') # ('incorrect', 'correction', corrector', 'correct', 'injector')

The suggestions are in sorted order, where the lower the index the closer to the input string.

Suffix Match

h.suffix_suggest('do') # ('doing', 'doth', 'doer', 'doings', 'doers', 'doest')


The module can also stem words, providing the stems for pluralization and other inflections.

h.stem('testers') # ('tester', 'test')
h.stem('saves') # ('save',)


Like stemming but return morphological analysis of the input instead.

h.analyze('permanently') # (' st:permanent fl:Y',)


Generate methods are NOT provided at this time due to the 1.7.0 build not producing any results for any inputs, included the documented one. If this is fixed or someone identifies the issue in the call pattern this will be added to the library in the future.

Bulk Requests

You can also request bulk actions against Hunspell. This will trigger a threaded (without a gil) request to perform the action requested. Currently just 'suggest' and 'stem' are bulk requestable.

h.bulk_suggest(['correct', 'incorect'])
# {'incorect': ('incorrect', 'correction', 'corrector', 'correct', 'injector'), 'correct': ('correct',)}
h.bulk_suffix_suggest(['cat', 'do'])
# {'do': ('doing', 'doth', 'doer', 'doings', 'doers', 'doest'), 'cat': ('cater', 'cats', "cat's", 'caters')}
h.bulk_stem(['stems', 'currencies'])
# {'currencies': ('currency',), 'stems': ('stem',)}
h.bulk_analyze(['dog', 'permanently'])
# {'permanently': (' st:permanent fl:Y',), 'dog': (' st:dog',)}

By default it spawns number of CPUs threads to perform the operation. You can overwrite the concurrency as well.

h.set_concurrency(4) # Four threads will now be used for bulk requests


You can also specify the language or dictionary you wish to use.

h = Hunspell('en_CA') # Canadian English

By default you have the following dictionaries available

  • en_AU
  • en_CA
  • en_GB
  • en_NZ
  • en_US
  • en_ZA

However you can download your own and point Hunspell to your custom dictionaries.

h = Hunspell('en_GB-large', hunspell_data_dir='/custom/dicts/dir')

Adding Dictionaries

You can also add new dictionaries at runtime by calling the add_dic method.

h.add_dic(os.path.join(PATH_TO, 'special.dic'))

Adding words

You can add individual words to a dictionary at runtime.


Furthermore you can attach an affix to the word when doing this by providing a second argument

h.add('silllies', "is:plural")

Removing words

Much like adding, you can remove words.


Asynchronous Caching

If you want to have Hunspell cache suggestions and stems you can pass it a directory to house such caches.

h = Hunspell(disk_cache_dir='/tmp/hunspell/cache/dir')

This will save all suggestion and stem requests periodically and in the background. The cache will fork after a number of new requests over particular time ranges and save the cache contents while the rest of the program continues onward. Yo'll never have to explicitly save your caches to disk, but you can if you so choose.


Otherwise the Hunspell object will cache such requests locally in memory and not persist that memory.

Language Preferences

  • Google Style Guide
  • Object Oriented (with a few exceptions)

Known Workarounds

  • On Windows very long file paths, or paths saved in a different encoding than the system require special handling by Hunspell to load dictionary files. To circumvent this on Windows setups, either set system_encoding='UTF-8' in the Hunspell constructor or set the environment variable HUNSPELL_PATH_ENCODING=UTF-8. Then you must re-encode your hunspell_data_dir in UTF-8 by passing that argument name to the Hunspell constructor or setting the HUNSPELL_DATA environment variable. This is a restriction of Hunspell / Windows operations.


Author(s): Tim Rodriguez and Matthew Seal



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distributions

cyhunspell-2.0.2-cp39-cp39-win_amd64.whl (2.1 MB view hashes)

Uploaded cp39

cyhunspell-2.0.2-cp39-cp39-win32.whl (2.1 MB view hashes)

Uploaded cp39

cyhunspell-2.0.2-cp38-cp38-win_amd64.whl (2.1 MB view hashes)

Uploaded cp38

cyhunspell-2.0.2-cp38-cp38-win32.whl (2.1 MB view hashes)

Uploaded cp38

cyhunspell-2.0.2-cp37-cp37m-win_amd64.whl (2.1 MB view hashes)

Uploaded cp37

cyhunspell-2.0.2-cp37-cp37m-win32.whl (2.1 MB view hashes)

Uploaded cp37

cyhunspell-2.0.2-cp36-cp36m-win_amd64.whl (2.1 MB view hashes)

Uploaded cp36

cyhunspell-2.0.2-cp36-cp36m-win32.whl (2.1 MB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page