PyNanoID

A tiny, secure, URL-friendly, unique string ID generator for Python, written in Rust.

• Safe. It uses hardware random generator. Can be used in clusters.
• Fast. 2-3 times faster than Python based generator.
• Compact. It uses a larger alphabet than UUID (A-Za-z0-9_-). So ID size was reduced from 36 to 21 symbols.

Installation

pip install pynanoid

Usage

from pynanoid import generate

print(generate())
# SxuPyeUFRnoWnNlwtLBvT

Symbols -,.() are not encoded in the URL. If used at the end of a link they could be identified as a punctuation symbol.

The Rust based high-performance generator is used by default if available. You can also use pure-Python based generator as shown here.

[!NOTE] If Rust based implementation is not available, the pure-Python generator will be automatically used.

If you want to reduce ID length (and increase the probability of collisions), you can pass the length as an argument.

from pynanoid import generate

print(generate(size=10))
# WtYW30_vPi

Don’t forget to check the safety of your ID length in ID collision probability calculator.

Custom Alphabet or Length

If you want to change the ID's alphabet or length, you can pass the alphabet as the first argument and the size as the second argument.

from pynanoid import generate

print(generate("1234567890abcdef", 10))
# bced90bd56

Non-secure generator is also available.

from pynanoid import non_secure_generate

print(non_secure_generate())
# JlJp1Od7zjlcrfIttk0JB

[!WARNING] Non-secure generator uses random.random internally. Hence it is not recommended for generating tokens or secrets.

Force Use Pure-Python Generator

If you want to use the pure-Python generator, you can use functions provided in pynanoid.nanoid.

from pynanoid.nanoid import generate, non_secure_generate

print(generate())  # wBM-LJLoliqnGTOf38Qf4
print(non_secure_generate())  # ekN1GQBxPNjKM3XFGVO8q

Benchmarks

We benchmark using pytest-benchmark. You can find the benchmark script in the tests/ directory.

You can run the benchmarks using the following command:

uv run pytest tests/benchmark.py --benchmark-histogram=assets/benchmark

Development

This project uses uv for Python packaging and maturin to build the Rust extension. You will also need a Rust toolchain.

# Create the virtual environment and build the extension.
uv sync

# Run the Python test suite.
uv run pytest

# Lint, format, and type-check.
uv run ruff check .
uv run ruff format .
uv run mypy .

# Rust checks.
cargo test
cargo clippy --all-targets --all-features
cargo fmt --all

# Rebuild the extension after changing Rust code.
uv run maturin develop

Credits

• Andrey Sitnik for Nano ID.
• Paul Yuan (@puyuan) for py-nanoid.