Install & Compatibility
Where this runs
tested against v2.0.0.20260508 · 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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.008s · 17.9MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.5s · import 0.005s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate
✓ from nanoid_stubs import generate
✗ from nanoid_stubs import generate
This quickstart demonstrates how to install both the `nanoid` library and its corresponding type stubs, `types-nanoid`. It then shows how to use `nanoid.generate` for secure IDs and `nanoid.non_secure_generate` for performance-critical, non-security-sensitive cases, all while leveraging the type hints provided by `types-nanoid` for static analysis.
import os
from nanoid import generate, non_secure_generate
def create_ids() -> None:
# Generate a cryptographically strong, URL-friendly unique ID
secure_id: str = generate()
print(f"Secure ID: {secure_id}")
# Generate a non-secure ID (for non-security-critical applications)
non_secure_id: str = non_secure_generate(size=10)
print(f"Non-Secure ID (10 chars): {non_secure_id}")
# Generate with a custom alphabet and size
custom_alphabet_id: str = generate('1234567890abcdef', 8)
print(f"Custom Alphabet ID: {custom_alphabet_id}")
if __name__ == "__main__":
create_ids()
Debug
Known issues
breakingType stub versions should ideally align with the major version of the runtime library they type. A mismatch between `types-nanoid` and the installed `nanoid` version can lead to incorrect type-checking results or errors.fixEnsure `nanoid` and `types-nanoid` are installed with compatible versions. For example, if `types-nanoid` is for `nanoid==2.0.0`, install both as `pip install "nanoid==2.0.0" "types-nanoid==2.0.0.*"`. Consult the `typeshed` repository for specific version compatibility notes.
affects: All versions of `types-nanoid` when `nanoid` is a different major version.
gotchaThere can be confusion with the JavaScript `@types/nanoid` package, which is deprecated because the JS `nanoid` library now includes its own types. In Python, however, `types-nanoid` is still necessary for type checking as the `nanoid` Python package does not typically bundle `py.typed` files for static analysis.fixFor Python projects, always install `types-nanoid` explicitly for type checking alongside the `nanoid` runtime library.
affects: All versions
gotchaThe `nanoid` library offers `non_secure_generate` which uses `random.random` internally. This function is explicitly "not recommended for generating tokens or secrets" due to its weaker cryptographic strength compared to `generate()`. Using it in security-sensitive contexts is a footgun.fixFor any security-critical ID generation (e.g., session tokens, API keys), always use `nanoid.generate()`. Reserve `nanoid.non_secure_generate()` only for cases where performance is prioritized over cryptographic strength and security is not a concern (e.g., temporary internal identifiers).
affects: All versions of `nanoid` and `types-nanoid`.
Upgrade
Version history
2.0.0.20260508latest on PyPI · released May 8, 2026
Audit
Dependencies
nanoidrequiredProvides runtime implementation for which these stubs offer type hints.