short-uuid generator

Short-UUID is a library for compressing standard UUIDs into shorter, URL-safe strings by re-encoding them using a larger character alphabet. Originally created by Stochastic Technologies and widely used through its Python implementation (with ports available in JavaScript, Go, and other languages), Short-UUID solves a common developer frustration: UUIDs are excellent for global uniqueness but their 36-character hyphenated hexadecimal representation is unnecessarily verbose for many practical purposes. Short-UUID takes any valid RFC 4122 UUID and deterministically encodes it into a shorter string, typically 22 characters when using the default base57 alphabet. Critically, this encoding is fully reversible. A Short-UUID can always be decoded back to the original UUID, preserving complete compatibility with existing UUID infrastructure, databases, and APIs. This makes Short-UUID fundamentally different from ID generators that produce new identifier formats. It is a bidirectional encoding layer on top of the UUID standard, not a replacement for it.

The library was motivated by the observation that standard UUID hex encoding is highly inefficient from an information-density perspective. A UUID contains 128 bits of information, but the standard representation uses 32 hexadecimal characters plus 4 hyphens, encoding only 4 bits per character. By using an alphabet with more characters, each character in the output can encode more bits of information, resulting in a shorter string that carries the same 128-bit payload. Short-UUID's default base57 alphabet excludes characters that are visually ambiguous (such as 0/O, 1/l/I) and characters that can cause problems in certain contexts (such as quotes and backslashes), striking a balance between compactness, readability, and safety across different environments.

How Short-UUID Works

At its core, Short-UUID performs a mathematical base conversion. A UUID is a 128-bit integer. In standard format, this integer is represented in base16 (hexadecimal) with hyphens inserted at fixed positions, producing the familiar 8-4-4-4-12 pattern like 550e8400-e29b-41d4-a716-446655440000. Short-UUID strips the hyphens, interprets the remaining 32 hex characters as a single large integer, and then converts that integer to a different base determined by the size of the chosen alphabet.

The default alphabet in the Python implementation contains 57 characters: 23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz. With 57 possible characters per position, each character encodes approximately 5.83 bits of information (log2(57)), compared to 4 bits per character in hexadecimal. The 128-bit UUID value therefore requires ceil(128 / log2(57)) = 22 characters in base57, a significant reduction from 36 characters (or 32 without hyphens).

The encoding process is deterministic and reversible because it is a pure mathematical transformation with no information loss. The same UUID will always produce the same Short-UUID string, and any valid Short-UUID string can be converted back to exactly one UUID. This bijectivity is what distinguishes Short-UUID from hashing or truncation approaches, which are lossy and irreversible.

Short-UUID also supports custom alphabets through its translator system. Developers can create translators with different character sets to produce outputs optimized for specific environments. For example, an alphabet containing only lowercase letters and digits would produce case-insensitive Short-UUIDs suitable for systems that normalize case, though the output would be slightly longer. An alphabet containing all 62 alphanumeric characters would produce the most compact output, while a smaller alphabet like base32 would produce longer but more constrained output.

When generating new identifiers, Short-UUID can create a fresh UUID (using standard UUID v4 random generation or any other version) and immediately encode it into the shorter format. This means Short-UUID inherits all the uniqueness and randomness properties of the underlying UUID version. A UUID v4 backed Short-UUID carries 122 bits of cryptographic randomness, while a UUID v1 backed Short-UUID embeds the original timestamp and node information, recoverable by decoding back to UUID format.

Use Cases

URL shortening and clean web routes. Short-UUID is commonly used to create cleaner, more shareable URLs. Instead of exposing a full UUID like /resources/550e8400-e29b-41d4-a716-446655440000, an application can use /resources/keATfB8JP2ggT7U9JZrpV with the Short-UUID encoding. The shorter URL is easier to share in emails, text messages, and social media posts, while the application can decode the Short-UUID back to the original UUID for database lookups. This approach avoids the complexity of maintaining a separate URL-to-ID mapping table, since the Short-UUID itself contains the complete UUID information.

Database systems with existing UUID infrastructure. Organizations that have standardized on UUIDs for their database primary keys can adopt Short-UUID for external-facing representations without modifying their storage layer. The database continues to store and index standard UUIDs, while APIs and user interfaces display the shorter encoded form. This is particularly valuable in systems where UUIDs are used for referential integrity across multiple services, because the Short-UUID is just a display format, not a new identifier type. There is no risk of sync issues or mapping inconsistencies.

API keys and user-facing tokens. Short-UUIDs provide a good balance of compactness and uniqueness for API keys, invite codes, and similar tokens. The 22-character default output is short enough to be easily copied and pasted, while the underlying UUID v4 provides sufficient randomness for security purposes. The excluded ambiguous characters in the default base57 alphabet reduce the likelihood of transcription errors when users manually enter tokens.

Cross-system identifier exchange. In microservices architectures where different systems have different identifier format constraints, Short-UUID serves as a useful interchange format. A system that stores UUIDs internally can transmit Short-UUIDs to a system with tighter length constraints, and the receiver can either use the Short-UUID directly or decode it back to a standard UUID.

Comparison with Alternatives

Short-UUID and UUID are not competing formats but complementary layers. Standard UUID provides the 128-bit uniqueness guarantee and RFC 4122 compliance, while Short-UUID provides a more compact textual representation. A Short-UUID and its decoded UUID refer to the same entity. If your system benefits from the universal recognizability of UUID format, use standard UUIDs directly. If you need shorter strings for URLs or user-facing contexts while maintaining UUID compatibility in your storage layer, Short-UUID is an efficient encoding solution.

Slugid takes a similar approach but uses base64url encoding instead of base57. This produces exactly 22 characters from a UUID using the URL-safe character set defined in RFC 4648. Both Slugid and Short-UUID produce 22-character strings, but the key distinction is that Slugid uses a standardized encoding (base64url) while Short-UUID uses a custom alphabet that excludes ambiguous characters. If you need integration with systems that already use base64url encoding (such as Mozilla's TaskCluster), Slugid is the natural fit. If you want to minimize visual ambiguity, Short-UUID's base57 alphabet is more suitable.

Compared to Nano ID, Short-UUID serves a fundamentally different purpose. Nano ID generates entirely new random identifiers with no relationship to UUIDs. A Nano ID cannot be converted to a UUID, and a UUID cannot be converted to a Nano ID. Short-UUID, by contrast, is always backed by a real UUID that can be recovered through decoding. If your application needs UUID compatibility for database storage, API integration, or regulatory compliance, Short-UUID preserves that compatibility while Nano ID does not. If you simply need short, random, unique strings with no UUID requirement, Nano ID is simpler and more direct.