ShortUUID

1.0.13 · active · verified Thu Apr 09

Shortuuid is a Python library that generates concise, unambiguous, and URL-safe UUIDs. It provides a simple API to generate UUIDs, encode integers, and decode strings using a customizable alphabet. The current version is 1.0.13, and releases are infrequent but stable, with a focus on maintenance.

Warnings

breaking Version 1.0.0 changed the internal byte order for encoding/decoding from Least Significant Byte (LSB) first to Most Significant Byte (MSB) first. This means UUIDs generated with `shortuuid` < 1.0.0 cannot be decoded by `shortuuid` >= 1.0.0, and vice-versa.
Fix: If you need to decode UUIDs generated with older versions, you must use a `shortuuid` version compatible with their generation. For new projects, ensure all components use 1.0.0+ consistently.
breaking Python 2.x support was dropped in version 1.0.0.
Fix: Projects requiring Python 2.x must use `shortuuid` < 1.0.0. For new development, ensure Python 3.6+ is used.
gotcha Choosing a custom alphabet or a very short length for generated UUIDs can significantly increase the probability of collisions. The default alphabet and length (22 characters) are chosen for a good balance of brevity and uniqueness.
Fix: Carefully consider the size and character set of your custom alphabet and the desired length. For most use cases, the default settings are sufficient. If generating many IDs, test for collision rates or stick to longer lengths/richer alphabets.
gotcha While the default alphabet is URL-safe, if you provide a custom alphabet, you are responsible for ensuring its characters are safe for your specific URL or filesystem context (e.g., avoiding characters like '/', '?', '&', '=', etc. without proper encoding).
Fix: When using `shortuuid.ShortUUID(alphabet=...)`, double-check that all characters in your custom alphabet are safe for the intended environment or use additional URL/filesystem encoding if necessary.

Install

pip install shortuuid Install latest version

Imports

shortuuid
```
import shortuuid
```

ShortUUID (for custom alphabet)

import shortuuid
su = shortuuid.ShortUUID(alphabet='abcdef0123456789')

Quickstart

This quickstart demonstrates how to generate short UUIDs, specify their length, and encode/decode integers using the default and a custom alphabet.

import shortuuid

# Generate a standard short UUID (default length 22)
my_uuid = shortuuid.uuid()
print(f"Generated UUID: {my_uuid}")

# Generate a UUID of a specific length
short_uuid_10 = shortuuid.uuid(length=10)
print(f"10-char UUID: {short_uuid_10}")

# Encode an integer to a short UUID string
encoded_str = shortuuid.encode(123456789)
print(f"Encoded integer: {encoded_str}")

# Decode a short UUID string back to an integer
decoded_int = shortuuid.decode(encoded_str)
print(f"Decoded integer: {decoded_int}")

# Use a custom alphabet
custom_su = shortuuid.ShortUUID(alphabet="0123456789abcdef")
custom_uuid = custom_su.uuid()
print(f"Custom alphabet UUID: {custom_uuid}")

view raw JSON →