---
id: retrie
version: "0.3.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# retrie — Efficient Trie-based regex unions for blacklist/whitelist filtering and one-pass mapping-based string replacing

License: permissive · Maintenance: active · Downloads: 101.5K/mo

## What it is and what it does

Retrie solves the performance problem of matching or replacing large sets of strings using naive regex unions. Instead of compiling a pattern like `(?:abc|abs|foo)` which becomes slow as the word list grows, it builds a Trie data structure that produces a more efficient pattern like `(?:ab[cs]|foo)`. The package provides three main classes—Trie (the underlying structure), Blacklist (filter out unwanted strings), Whitelist (keep only allowed strings), and Replacer (perform bulk find-and-replace)—each with options to match whole words or substrings.

The implementation is pure Python with minimal dependencies (only typing and cached-property), making it portable and easy to integrate. It supports both Python 2.7 and modern Python versions, and has been actively maintained since its 2020 release. The API is straightforward: instantiate a class with a word list or mapping, optionally configure matching behavior, and call methods like `filter()`, `cleanse_text()`, or `replace()` on your input.

Use it for:

- Filter spam or profanity from user-generated text by maintaining a blacklist of forbidden terms.
- Extract only whitelisted keywords or entities from documents for data cleaning pipelines.
- Perform bulk find-and-replace operations (e.g., synonym substitution, URL rewriting) in a single pass.
- Build content moderation systems that need to match many patterns efficiently without regex compilation overhead.
- Normalize or standardize text by replacing multiple variant spellings or abbreviations with canonical forms.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Builds efficient Trie-based regex patterns for fast matching and replacing strings in bulk, avoiding the performance penalty of simple regex unions on large word sets.

Yes. Retrie is a focused, well-maintained tool that solves a real performance problem for bulk string matching and replacement. Its low install friction, permissive MIT license, and broad Python version support make it a safe dependency. Use it when you need to filter or replace large word sets and regex performance matters; skip it if you only have a handful of patterns to match.

## Install

pip install retrie
uv add retrie
poetry add retrie

## Installing retrie

Before you install: Low friction: pure Python, no compiled dependencies, and actively maintained with a recent commit on 2026-08-01. Supports Python 2.7 through 3.12, though reliance on the unmaintained cached-property backport for older Python versions may warrant attention in long-term projects.

License in practice: MIT license permits commercial and private use with minimal restrictions—include a copy of the license and you are free to modify and distribute.

Quickstart:

pip install retrie

from retrie.retrie import Blacklist
blacklist = Blacklist(["abc", "foo"], match_substrings=False)
blacklist.cleanse_text("good abc foobar")

Verify before relying:

- Whether the Trie structure provides measurable performance gains for specific word-set sizes or text lengths.
- How the package handles Unicode edge cases or non-ASCII character matching in practice.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 101.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

trie regex pattern matching, efficient string replacement, blacklist whitelist filtering, bulk regex matching, trie-based text search, fast regex unions, string filtering performance, text-processing, regex-optimization, data-filtering

[View on SkillFed](https://skillfed.io/packages/retrie) · [View on PyPI](https://pypi.org/project/retrie/)