nanoid

library2.0.0pypypi✓ verified 23d ago

Nano ID is a tiny, secure, URL-friendly, unique string ID generator for Python. It provides compact IDs that are safer and shorter than UUIDs by using a larger alphabet and cryptographically strong random APIs. The current stable version is 2.0.0, and it is actively maintained.

serialization

pip install nanoid

github ↗package ↗

INSTALL

IMPORT

SIG · NANOID

nanoid

serializationpythonv2.0.0

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · 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.008s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.004s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

generate

✓ from nanoid import generate

non_secure_generate

✓ from nanoid import non_secure_generate

Use this for non-security-critical applications where performance is prioritized, as it uses pseudo-random generation.

Quickly generate secure, URL-friendly unique IDs. You can specify the length and a custom alphabet. A faster, non-secure generator is also available for less sensitive use cases.

from nanoid import generate, non_secure_generate # Generate a default 21-character, URL-friendly ID id_default = generate() print(f"Default ID: {id_default}") # Generate an ID with a specified length id_short = generate(size=10) print(f"Short ID (10 chars): {id_short}") # Generate an ID with a custom alphabet and length id_custom = generate('1234567890abcdef', 16) print(f"Custom Alphabet ID: {id_custom}") # Generate a non-secure ID (faster, but not for sensitive use) id_non_secure = non_secure_generate() print(f"Non-Secure ID: {id_non_secure}")

Debug

Known issues

breakingVersion 2.0.0 changed the default alphabet, replacing '~' with '-'. The default ID length was also reduced from 22 to 21 characters.

fix

If migrating from a pre-2.0.0 version, explicitly define the old alphabet and length if consistent ID generation is critical for existing data. Otherwise, IDs generated by v2.0.0 will be different by default.

affects: 2.0.0 and later

gotchaThe `non_secure_generate` function uses `random.random` internally and is not cryptographically strong. It is explicitly not recommended for security-sensitive applications like generating tokens or secrets.

fix

Always use `generate()` for sensitive applications, which employs cryptographically strong random APIs. Only use `non_secure_generate()` when performance is critical and security is not a concern.

affects: All versions where `non_secure_generate` is available

gotchaReducing the ID length (e.g., `generate(size=10)`) increases the probability of collisions.

fix

Always use an ID collision probability calculator (often linked in Nano ID documentation for various languages) to determine a safe ID length based on your expected number of IDs and desired collision probability.

affects: All versions

gotchaWhen using custom alphabets, be cautious with characters like `-,.()` at the end of a link in URLs, as they might be misinterpreted as punctuation by some systems.

fix

Prefer the default URL-friendly alphabet or ensure that custom alphabets avoid problematic characters for URL contexts. If problematic characters are necessary, ensure proper URL encoding.

affects: All versions

gotchaNanoIDs are non-sequential. Using them as clustered primary keys in a database can lead to significant performance overhead during inserts, as the database may need to reorder records physically on disk to maintain the clustered index order.

fix

Avoid using NanoIDs (or UUIDs) as clustered primary keys if insert performance is critical. Consider using them as regular unique identifiers and a separate sequential primary key for clustering, or evaluate the impact on your specific database system.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'nanoid'

The 'nanoid' package is not installed in your Python environment.

fix

Install the package using pip: `pip install nanoid`

TypeError: 'module' object is not callable

You are trying to call the 'nanoid' module directly as a function after `import nanoid`, but the ID generation functionality is exposed via the `generate` function within the module.

fix

Import the `generate` function explicitly and call it: `from nanoid import generate; id = generate()`

AttributeError: module 'nanoid' has no attribute 'nanoid'

You have imported the 'nanoid' module (e.g., `import nanoid`) and are attempting to call a non-existent attribute named 'nanoid' within it (e.g., `nanoid.nanoid()`), often a pattern from other language implementations.

fix

The correct function to generate an ID is `generate`. Use `from nanoid import generate; id = generate()` or if you must use `import nanoid`, then `id = nanoid.generate()`.

from nanoid import nanoid

You are attempting to import a function named 'nanoid' directly from the 'nanoid' package, but the primary ID generation function is named 'generate'.

fix

Import the correct function named 'generate': `from nanoid import generate`

Upgrade

Version history

2.0.0latest on PyPI · released Nov 20, 2018

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/puyuan/py-nanoid ↗

packagehttps://pypi.org/project/nanoid/ ↗