Install & Compatibility
Where this runs
tested against v2.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Automaton
✓ from ahocorasick import Automaton
✗ from pyahocorasick import Automaton
The Python module is named 'ahocorasick', not 'pyahocorasick'.
Initialise an `Automaton`, add words (and optional values), then call `make_automaton()` to compile the trie into a searchable Aho-Corasick automaton. The `iter()` method yields `(end_index, value)` for all matches found in the input string.
import ahocorasick
# Create an Automaton object
A = ahocorasick.Automaton()
# Add keywords and associated values (optional)
words_to_find = {
"apple": "fruit",
"apply": "verb",
"banana": "fruit",
"band": "music"
}
for idx, (word, value) in enumerate(words_to_find.items()):
A.add_word(word, (idx, value))
# Finalize the automaton for efficient searching
A.make_automaton()
# Search in a haystack string
haystack = "I like to eat an apple and apply for a new band that plays banana songs."
print("Found matches:")
for end_index, (insertion_order, original_value) in A.iter(haystack):
start_index = end_index - len(original_value) + 1
print(f" Found '{original_value}' at ({start_index}, {end_index})")
# Example of retrieving a value (trie-like behavior)
print(f"\nValue for 'apple': {A.get('apple')}")
# Check existence
print(f"Is 'apple' in the automaton? {'apple' in A}")
Debug
Known issues
breakingPython 3.9 support was dropped in v2.3.0. Python 3.8 support was dropped in v2.2.0, and Python 3.6/3.7 in v2.1.0. Users on older Python versions must use an earlier `pyahocorasick` release.fixUpgrade to a supported Python version (3.10+) or pin `pyahocorasick` to an older version compatible with your Python environment (e.g., `<2.1.0` for 3.6/3.7, `<2.2.0` for 3.8, `<2.3.0` for 3.9).
affects: >=2.1.0
breakingThe internal trie representation changed in v1.4.0, breaking compatibility with pickle and `save()` formats from previous versions. Automata pickled or saved with older versions cannot be loaded by v1.4.0 or newer.fixRebuild your automaton if it was pickled or saved with a version prior to 1.4.0 when upgrading to 1.4.0 or later.
affects: >=1.4.0
gotchaThe correct Python module to import is `ahocorasick`, not `pyahocorasick`. Attempting to import `pyahocorasick` will result in an `ImportError`.fixAlways use `import ahocorasick` to access the library's functionality.
affects: All versions
gotchaAfter adding all words to the `Automaton` (which acts as a Trie initially), you must call the `make_automaton()` method to finalize it into an Aho-Corasick automaton before performing searches with `iter()` or related methods. Failing to do so will result in an `Automaton` in `TRIE` kind state, not `AHOCORASICK` kind.
gotchaInstalling `pyahocorasick` from source requires a C compiler to build the CPython extension. While pre-built wheels are generally available on PyPI, source installation without a compiler will fail.fixEnsure a C compiler (e.g., GCC on Linux, Xcode Command Line Tools on macOS, MSVC on Windows) is installed and configured if you need to install from source or if pre-built wheels are not available for your specific platform/Python version.
affects: All versions (when installing from source)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ahocorasick'
The `pyahocorasick` package is installed, but the import statement incorrectly uses `pyahocorasick` instead of `ahocorasick`, or the package is not installed at all.
fixEnsure the package is installed using `pip install pyahocorasick`, and import it as `import ahocorasick`.
ERROR: Failed building wheel for pyahocorasick error: Microsoft Visual C++ 14.0 is required. Get it with "Build Tools for Visual Studio"
`pyahocorasick` is a C extension, and building it from source on Windows requires a compatible C++ compiler (like Visual C++ Build Tools). If pre-built wheels are not available for your specific Python version or OS, `pip` attempts to compile it, leading to this error.
fixInstall the "Build Tools for Visual Studio" from Microsoft's website and ensure the 'Desktop development with C++' workload is selected during installation.
AttributeError: module 'ahocorasick' has no attribute 'Automaton'
This error typically occurs when an older or different `ahocorasick` package (not `pyahocorasick`) is installed, or if there's an incomplete installation or a name clash, preventing the `Automaton` class from being found in the imported `ahocorasick` module.
fixEnsure only `pyahocorasick` is installed (you might need to `pip uninstall ahocorasick` and `pip uninstall pyahocorasick` first) and then `pip install pyahocorasick`. Verify your import is `import ahocorasick`.
TypeError: 'str' object cannot be interpreted as a buffer
The `pyahocorasick` library's C extension often expects byte strings for certain operations. Passing a standard Python string (`str`) when a byte string (`bytes`) is expected causes this error.
fixEncode your Python string to bytes before passing it to the `pyahocorasick` method, for example, `text.encode('utf-8')`. Upgrade
Version history
2.3.1latest on PyPI · released Apr 27, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer. Prior versions (3.6-3.9) are no longer supported in recent releases.