Shorten UUIDs to 22 characters.

uuid58 turns a 36-character UUID into a 22-character Base58 string, and back. It is safe in URLs, sorts in the same order as the UUID, and leaves out look-alike characters (0, O, I, l).

The format is fixed by a stable, versioned spec, with its core guarantees proven in Lean, and checked by over 200 shared test vectors, so every implementation (JavaScript, Go, Python, Rust, PostgreSQL, and more) produces the same string, today and in future releases.

UUID · 36f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf
uuid58 · 22XDY9dmBbcMBXqcRvYw8xJ2

UUID ⇄ Base58 converter

Why uuid58

  • Two-way UUID ⇄ Base58 conversion

    Convert UUIDs to 22-character Base58 strings and back without losing information. Keep UUIDs in your database; use uuid58 in URLs, APIs, and logs.

  • Easy to read, copy, and share

    Always 22 characters, URL-safe, and free of look-alikes (0, O, I, l). No separators, so you can select the whole ID with a double-click.

  • Preserves UUID sort order

    uuid58 preserves UUID order when sorted by ASCII value, keeping UUIDv7 IDs time-ordered. Use binary or C collation for database sorting.

  • Multi-language support

    Implementations across languages follow the same specification. Switch languages without converting or reissuing your existing uuid58 IDs.

  • Proven correct, not just tested

    Lean proofs show that conversion is lossless, always 22 characters, and order-preserving for every UUID. They also check the Rust and JavaScript libraries against the spec on every input. Every library passes over 200 shared test vectors.

  • A stable, strict specification

    The specification defines the format and validation rules, with a stable encoding throughout 1.x. Use it with shared test vectors to build and verify your own implementation, including with AI.

How uuid58 compares

OptionLengthStill a UUID?Notes
uuid5822YesBitcoin Base58, fixed length, sortable, one spec across languages.
Standard UUID36YesLong, and the hyphens stop a double-click from selecting the whole ID.
short-uuid (npm)22YesFlickr Base58 by default: a different alphabet order, so its strings differ from uuid58.
shortuuid (Python)22YesA 57-character alphabet; its strings differ from uuid58.
slugid22YesURL-safe Base64, so IDs can contain - and _.
ULID26NoIts own format (Crockford Base32), 128-bit compatible with UUID but written differently.
Nano ID21NoRandom IDs, not UUIDs. Nothing to convert back to.
Firestore auto-ID20NoRandom alphanumeric IDs from the Firestore SDKs. Not sortable, nothing to convert back.
SqidsVariesNoEncodes integers such as database row IDs, not UUIDs. Length grows with the number.

Pick uuid58 when you already use UUIDs (or want to), need them short in URLs and APIs, and want every service and language to agree on the string.

Libraries for every language

Each library encodes UUIDs as uuid58 strings and decodes them back. All follow the uuid58 specification 1.1.0 and pass its test vectors. The samples below use the values from the converter.

npm i @nakanoaas/uuid58
import { uuid58, uuid58Decode, uuid58Encode } from "@nakanoaas/uuid58";

uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
// => "XDY9dmBbcMBXqcRvYw8xJ2"

uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2");
// => "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"

uuid58(); // a new random UUID, encoded

Command line

uuid58 is a small command-line tool built on the Go implementation: a single static binary with no dependencies. The example uses the values from the converter.

Install

brew install nakanoasaservice/tap/uuid58

macOS and Linux. Installs a prebuilt binary.

Prebuilt binaries for macOS, Linux, and Windows are on GitHub Releases. The CLI ships with the next Go release; until then, only the Nix flake installs it.

Try without installing

With Nix, nix run builds the CLI and runs it on the spot, leaving nothing installed. Put the command and its arguments after --.

nix run github:nakanoasaservice/uuid58 -- gen

Usage

Each command takes values as arguments, or reads one per line from standard input when there are none, so it fits in a pipeline. Every input is processed, and each invalid one is reported on standard error with its error kind.

$ uuid58 encode f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf
XDY9dmBbcMBXqcRvYw8xJ2

$ uuid58 decode XDY9dmBbcMBXqcRvYw8xJ2
f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf

$ uuid58 validate XDY9dmBbcMBXqcRvYw8xJ2 abc
uuid58 validate: "abc": invalid_length

$ uuid58 gen -n 2
JSGfCL3atpZzP7Qh5Hrt3C
SaBF5eq63TPKCD46a2Gecc

$ cut -d, -f1 users.csv | uuid58 encode > ids.txt
CommandWhat it does
uuid58 encode [uuid ...]UUID to uuid58. Accepts the hyphenated form and 32 hex digits, in either case.
uuid58 decode [uuid58 ...]uuid58 to a lowercase hyphenated UUID.
uuid58 validate [uuid58 ...]Exits with 0 if every input is a valid uuid58, and reports each invalid one. Alias: check.
uuid58 gen [-n count] [-uuid]New random version 4 UUIDs as uuid58. -uuid adds the UUID after a tab. Alias: new.
uuid58 --version, --helpPrints the version or the usage.

Exit status: 0 on success, 1 if any input was invalid, 2 on a usage error.

FAQ

Will the format change?

No. Spec 1.1.0 fixes the alphabet, the padding, and the accepted inputs. Any change that would alter an encoded string needs a new major version of the spec, and every implementation is tested against the same versioned test vectors.

Does it work with UUIDv7?

Yes. uuid58 encodes any 128-bit UUID, and strings sort in the same order as the UUIDs, so UUIDv7 IDs stay time-ordered when sorted as strings.

Can I use uuid58 for Firestore document IDs?

Yes. uuid58 strings meet Firestore's document ID rules. Use random (v4) UUIDs: Firestore advises against sequential IDs, which can cause write hotspots. If you later move to a relational database, decode each ID into a UUID column; references between records carry over as they are.

What exactly is formally verified?

The spec's guarantees: decoding an encoded UUID returns it unchanged, every encoding is 22 characters, and string order matches UUID order. Lean also proves that the JavaScript library's public functions and the Rust library's numeric codec, validator, UUID text parser, and UUID text formatter follow the spec for every input. Rust's decode_to_uuid_buf writes and returns the canonical UUID on success and preserves the caller's buffer on error. The proofs are rechecked against the current source on every change. The other libraries are checked with the shared test vectors. Proof scope and trust assumptions

I found a 22-character ID like XDY9dmBbcMBXqcRvYw8xJ2. Is it uuid58?

If it uses only Base58 characters (no 0, O, I, or l) and decodes in the converter above, it is likely a uuid58-encoded UUID.