⚠️ Not encryption. Hashids obfuscates ids for convenience. It is not cryptographically secure, whatever the salt. Don't use it to protect secrets.

Installation

pip install harsh-ids

Quick start

from harsh_ids import Harsh

hashids = Harsh(salt="this is my salt", min_length=8)

hashids.encode(1, 2, 3)          # 'GlaHquq0'
hashids.decode('GlaHquq0')       # (1, 2, 3)

hashids.encode_hex('deadbeef')   # 'kRNrpKlJ'   (MongoDB ObjectIds, etc.)
hashids.decode_hex('kRNrpKlJ')   # 'deadbeef'

Constructor options

API

Using the Python hashids package today? Hashids is exported as an alias for Harsh, so swapping the import is enough. The main difference is error handling: hashids returns '' or () on bad input, this package raises. If your code depends on those empty returns, wrap the calls in a try.

Notes

• ASCII only — salt, alphabet, and separators must be ASCII: the underlying harsh crate operates on bytes, so multi-byte UTF-8 would not round-trip.
• Tuples out — decode always returns a tuple, even for a single number.
• Strict hex — decode_hex re-encodes and verifies its result, so a hashid that does not round-trip raises ValueError instead of silently returning corrupted hex (a flaw in the underlying crate).
• Immutable & pickleable — instances are frozen value objects; copy, deepcopy, and pickle all work.
• Releases the GIL — selectively — the pure-Rust computation runs with the interpreter lock released (Python::detach) once a call is big enough to be worth the handoff (≥ 16 values or ≥ 32 characters); tiny calls stay on the GIL-held fast path. For bulk work, encode_many/decode_many pay the Python/Rust boundary once and run the whole batch with the GIL released. Instances are shared safely across threads either way.
• No profanity by default — the 14 default separators (cfhistuCFHISTU) are held out of the alphabet and never placed next to each other. English curse words are built from the lowercase seven (cfhistu), so ids can't spell them.

Development

Source builds need a Rust toolchain; wheels are built as abi3, so one wheel covers CPython 3.9 and newer.

uv sync              # installs the project + the dev group (pytest)
uv run pytest        # includes known-answer vectors from the upstream crate
uv build --wheel     # or: maturin build --release

Benchmarks

Environment: Tested on Windows 11 with Python 3.11.13 using pytest-benchmark.

Excluded from the default test run; run explicitly:

uv run --group bench pytest benchmarks --benchmark-only

Add --benchmark-autosave to store a run, --benchmark-compare to diff against the stored one.

benchmarks/test_compare.py benchmarks against the official pure-Python hashids package (20–30× slower on the same machine) and doubles as a cross-implementation consistency check. For bulk workloads encode_many/decode_many run 2000 ids in a single boundary crossing (~0.5 µs/id); small calls hold the GIL, so threading batches of them serializes cleanly, while long-payload decoding scales ~3.6× across 4 pooled threads. Treat the medians above as same-machine regression baselines, not absolute claims.

License

MIT