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.
f4b247fd-1f87-45d4-aa06-1c6fc0a8dfafXDY9dmBbcMBXqcRvYw8xJ2UUID ⇄ 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
| Option | Length | Still a UUID? | Notes |
|---|---|---|---|
| uuid58 | 22 | Yes | Bitcoin Base58, fixed length, sortable, one spec across languages. |
| Standard UUID | 36 | Yes | Long, and the hyphens stop a double-click from selecting the whole ID. |
| short-uuid (npm) | 22 | Yes | Flickr Base58 by default: a different alphabet order, so its strings differ from uuid58. |
| shortuuid (Python) | 22 | Yes | A 57-character alphabet; its strings differ from uuid58. |
| slugid | 22 | Yes | URL-safe Base64, so IDs can contain - and _. |
| ULID | 26 | No | Its own format (Crockford Base32), 128-bit compatible with UUID but written differently. |
| Nano ID | 21 | No | Random IDs, not UUIDs. Nothing to convert back to. |
| Firestore auto-ID | 20 | No | Random alphanumeric IDs from the Firestore SDKs. Not sortable, nothing to convert back. |
| Sqids | Varies | No | Encodes 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/uuid58import { 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, encodedgo get github.com/nakanoasaservice/uuid58/goimport uuid58 "github.com/nakanoasaservice/uuid58/go"
s, err := uuid58.Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
// s == "XDY9dmBbcMBXqcRvYw8xJ2"
u, err := uuid58.Decode("XDY9dmBbcMBXqcRvYw8xJ2")
// u == "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"pip install uuid58import uuid58
uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
# 'XDY9dmBbcMBXqcRvYw8xJ2'
uuid58.decode("XDY9dmBbcMBXqcRvYw8xJ2")
# 'f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'cargo add uuid58let id = uuid58::encode_uuid_str("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")?;
assert_eq!(id, "XDY9dmBbcMBXqcRvYw8xJ2");
let uuid = uuid58::decode_to_uuid_string("XDY9dmBbcMBXqcRvYw8xJ2")?;
assert_eq!(uuid, "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");implementation("io.github.nakanoasaservice:uuid58:0.1.0")import io.github.nakanoasaservice.uuid58.Uuid58;
Uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
// "XDY9dmBbcMBXqcRvYw8xJ2"
Uuid58.decode("XDY9dmBbcMBXqcRvYw8xJ2");
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"implementation("io.github.nakanoasaservice:uuid58:0.1.0")import io.github.nakanoasaservice.uuid58.Uuid58
Uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
// "XDY9dmBbcMBXqcRvYw8xJ2"
Uuid58.decode("XDY9dmBbcMBXqcRvYw8xJ2")
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf".package(url: "https://github.com/nakanoasaservice/uuid58-swift.git", from: "0.1.0")import UUID58
try uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
// "XDY9dmBbcMBXqcRvYw8xJ2"
try uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2")
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"Not released yet. The install command works once the first version is published.
dotnet add package Uuid58using NakanoAsAService.Uuid58;
Uuid58.EncodeUuidString("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
// "XDY9dmBbcMBXqcRvYw8xJ2"
Uuid58.Decode("XDY9dmBbcMBXqcRvYw8xJ2");
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"Not released yet. The install command works once the first version is published.
composer require nakanoasaservice/uuid58use NakanoAsAService\Uuid58\Uuid58;
Uuid58::encode('f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf');
// 'XDY9dmBbcMBXqcRvYw8xJ2'
Uuid58::decode('XDY9dmBbcMBXqcRvYw8xJ2');
// 'f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'Not released yet. The install command works once the first version is published.
bundle add uuid58require "uuid58"
Uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
# => "XDY9dmBbcMBXqcRvYw8xJ2"
Uuid58.decode("XDY9dmBbcMBXqcRvYw8xJ2")
# => "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"Not released yet. The install command works once the first version is published.
dart pub add uuid58import 'package:uuid58/uuid58.dart';
uuid58Encode('f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf');
// 'XDY9dmBbcMBXqcRvYw8xJ2'
uuid58Decode('XDY9dmBbcMBXqcRvYw8xJ2');
// 'f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'curl -fsSL https://raw.githubusercontent.com/nakanoasaservice/uuid58/main/postgres/uuid58.sql | psqlSELECT uuid58_encode('f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'::uuid);
-- XDY9dmBbcMBXqcRvYw8xJ2
SELECT uuid58_decode('XDY9dmBbcMBXqcRvYw8xJ2');
-- f4b247fd-1f87-45d4-aa06-1c6fc0a8dfafCommand 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/uuid58macOS and Linux. Installs a prebuilt binary.
nix profile install github:nakanoasaservice/uuid58Builds from source.
go install github.com/nakanoasaservice/uuid58/go/cmd/uuid58@latestNeeds Go 1.26 or later. Installs into $(go env GOPATH)/bin.
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 -- genUsage
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| Command | What 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, --help | Prints 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.