Profanex — fast profanity detection and filtering for Python

Profanex is a Rust-powered Python profanity filter for detecting, locating, and masking bad words and phrases. It provides Unicode-safe spans, allowlists, optional fuzzy matching, configurable word lists, and parallel batch processing.

Installation · Quick start · Configuration · Documentation · Benchmarks

Why Profanex?

• A Rust-powered Aho-Corasick fast path for exact and multi-word phrase matching
• Unicode-safe Python string spans and consistent contains, find, and clean results
• Categories, allowlists, and custom YAML lexicons for application-specific moderation policies
• Optional fuzzy and evasion matching when recall matters more than raw throughput
• Ordered batch and iterator APIs with optional parallel processing

Defaults are conservative: all categories are enabled, word boundaries are enforced, and fuzzy and aggressive normalization are disabled.

Requirements

• Python 3.11 or newer
• A supported abi3 prebuilt wheel (one wheel covers 3.11+), or Rust 1.85.0 and maturin when building from source

Installation

uv add profanex
# or: python -m pip install profanex

For local development, see CONTRIBUTING.md.

Quick start

from profanex import Filter

f = Filter()
text = "You are a b1tch!"

print(f.contains(text))  # True
print(f.find(text))
print(f.clean(text))     # You are a *****!
print(f.analyze(text))   # (True, "You are a *****!") from one scan

Every match uses a half-open Python string span. Each Match also carries the lexicon term, categories, match kind (exact / phrase / fuzzy), and fuzzy score (100 for exact and phrase matches):

match = f.find(text)[0]
assert match.text == text[match.start:match.end]
assert match.term and match.categories

Filter.from_defaults() is equivalent to Filter() / Filter(FilterConfig()).

Configuration

from profanex import Category, Filter, FilterConfig

config = FilterConfig(
    categories=frozenset(category for category in Category if category != Category.SLURS),
    extra_banned={"project-specific-term"},
    extra_allowlist=["projectcodename"],
    enable_fuzzy=True,
    threshold=85,
    mask="stars",
)
f = Filter(config)

banned and banned_path cannot be used together; the same applies to allowlist and allowlist_path. Allowlist entries have final precedence after normalization, so an explicit allowed term can disable a packaged or custom banned term.

Default leet covers digit/@/$ substitutions and infix !→i when the token contains an ASCII alphabetic anchor (for example b1tch, a55, sh!t). Numeric-only tokens such as 455 and 80085 are left unchanged even beside non-Latin text, and trailing ! is unchanged. Common asterisk masks (f*ck, sh*t) are packaged lexicon literals. For stronger evasion (fuuuck, f.u.c.k), opt in:

f = Filter(FilterConfig(
    normalize_repeated_chars=True,
    normalize_separated_runs=True,
))

Keep enable_fuzzy=True separate and measure it; it is off by default. For recipes, false-positive tradeoffs, and performance implications, see the configuration guide.

Custom YAML may be a flat list or a category mapping:

general:
  - dang
sexual:
  - example-term

Batch processing

Batch methods preserve input order. Parallel processing is opt-in:

texts = ["clean", "what the fuck", "please pass"]

flags = f.contains_many(texts)
matches = f.find_many(texts)
cleaned = f.clean_many(texts, parallel=True, workers=4)
flags, cleaned = f.analyze_many(texts, parallel=True, workers=4)

# Streaming variants: iter_contains, iter_find, iter_clean, iter_analyze
streamed = list(f.iter_clean(texts, chunk_size=1_000))

Use analyze / analyze_many when both a flag and cleaned text are needed; they avoid scanning each input twice. Custom mask callbacks work only with serial cleaning. Explicit worker counts are capped at 256, and applications with their own thread pools should set a smaller value to avoid oversubscription.

More information

• Documentation
• API reference
• Configuration guide — when to enable each option and performance tradeoffs
• How Profanex works
• Accuracy methodology and results
• Benchmark methodology and results
• Competitive benchmarks
• Limitations and threat model
• Fixture schema
• Lexicon provenance — upstream attribution, modifications, and data licensing

License

The Profanex software is MIT licensed. The packaged banned lexicon is a modified CC BY 4.0 dataset; see lexicon provenance.