marisa-trie

library1.4.1pypypi✓ verified 25d ago

marisa-trie provides static, memory-efficient, and fast Trie-like data structures for Python, wrapping the C++ MARISA library. It's ideal for use cases like autocomplete, spell checkers, and storing large sets of strings or byte sequences for fast prefix matching and lookup. The library is actively maintained with regular updates to support new Python versions and minor feature enhancements.

serialization data

pip install marisa-trie

github ↗package ↗

INSTALL

IMPORT

SIG · MARISA-TRIE

marisa-trie

serializationpythonv1.4.1

Install

1.8s avg

Import

—

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 25.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.000s · 23MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Trie

✓ from marisa_trie import Trie

Trie is an alias for BytesTrie and expects byte strings.

BytesTrie

✓ from marisa_trie import BytesTrie

The primary Trie implementation for byte strings.

RecordTrie

✓ from marisa_trie import RecordTrie

For storing structured data (records) associated with keys.

StringTrie

✓ from marisa_trie import StringTrie

Introduced in v1.4.0, specifically for string-to-string mappings without manual encoding.

Demonstrates creating a BytesTrie (the default Trie) and a StringTrie, then performing basic lookups and prefix searches. Note that BytesTrie expects byte strings for all operations.

from marisa_trie import BytesTrie, StringTrie # Example with BytesTrie (most common, requires bytes) words_bytes = [b'apple', b'apricot', b'banana', b'bandana', b'cherry'] b_trie = BytesTrie(words_bytes) print(f"'apple' in BytesTrie: {b'apple' in b_trie}") print(f"Words starting with 'ap': {list(b_trie.keys(b'ap'))}") # Example with StringTrie (requires strings, new in 1.4.0) words_str = ['hello', 'world', 'helium', 'wonder'] s_trie = StringTrie(words_str) print(f"'hello' in StringTrie: {'hello' in s_trie}") print(f"Words starting with 'h': {list(s_trie.keys('h'))}")

Debug

Known issues

breakingPython 3.7 and 3.8 support was dropped. Users on these versions must upgrade Python or stick to older marisa-trie versions.

fix

Upgrade to Python 3.9 or newer. For Python 3.7/3.8, use marisa-trie<1.3.0.

affects: >=1.3.0

gotchaMARISA tries are immutable after creation. You cannot add or remove keys once the trie is built. To modify, you must build a new trie.

fix

Plan your data set in advance. If dynamic updates are needed, MARISA Trie might not be the right choice, or you'll need to re-build the trie periodically.

affects: all

gotchaThe default `Trie` and `BytesTrie` classes expect `bytes` objects, not `str`. Operations like `trie.keys(b'prefix')` or `b'word' in trie` require byte strings.

fix

Encode strings to bytes (e.g., `s.encode('utf-8')`) before passing them to `BytesTrie` methods. Alternatively, use `StringTrie` (available since v1.4.0) if you primarily work with `str` type keys and values.

affects: all

Errors

Common errors & fixes

command 'gcc' failed with exit status 1

This error typically occurs during installation on Linux or macOS when the necessary C++ compiler (like GCC or Clang) or its development headers are missing or not properly configured, as `marisa-trie` is a wrapper around a C++ library.

fix

On Debian/Ubuntu: `sudo apt-get update && sudo apt-get install build-essential python3-dev`. On Fedora/RHEL: `sudo dnf install @development-tools python3-devel`. On macOS, install Xcode Command Line Tools: `xcode-select --install`.

ModuleNotFoundError: No module named 'marisa_trie'

This error indicates that the `marisa-trie` package was not successfully installed or is not accessible in the current Python environment.

fix

Ensure the package is installed in your active environment: `pip install marisa-trie`. If using virtual environments, activate it before installing. If it's still missing, verify the installation path or check for more detailed errors during the `pip install` command.

AttributeError: 'tuple' object has no attribute 'encode'

This error arises when attempting to build a `marisa_trie.Trie` with an iterable containing elements that are not strings or bytes (e.g., tuples), because the underlying C++ library expects string-like or byte-like sequences that can be encoded.

fix

Ensure all elements in the input iterable for `marisa_trie.Trie` are strings (e.g., `['key1', 'key2']`) or byte sequences. If you need to store complex objects, consider using `marisa_trie.RecordTrie` or `marisa_trie.BytesTrie` which support richer data types.

'PyTypeObject {aka struct _typeobject}' has no member named 'tp_print'

This specific build error occurs when installing `marisa-trie` on Python 3.9 or newer, as the `tp_print` member was removed from the `PyTypeObject` structure in Python 3.9, causing compilation failures for older versions of the `marisa-trie` Cython wrapper.

fix

Upgrade to a `marisa-trie` version that officially supports Python 3.9+ (e.g., 1.x or later). The project actively maintains support for newer Python versions. `pip install --upgrade marisa-trie` should fetch a compatible version.

Upgrade

Version history

1.4.1latest on PyPI · released Apr 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pytries/marisa-trie ↗

packagehttps://pypi.org/project/marisa-trie/ ↗