uuid58 (Python)
Encode UUIDs as 22-character Base58 strings, and back.
f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf <-> XDY9dmBbcMBXqcRvYw8xJ2
- Always exactly 22 characters, using the Bitcoin Base58 alphabet (no
0,O,I,l). - Order-preserving: sorting uuid58 strings by code point sorts the UUIDs numerically (useful with UUIDv7).
- Strict: implements the uuid58 specification and passes its test vectors.
- No dependencies, fully typed (
py.typed), CPython 3.10+.
Install
pip install uuid58
or uv add uuid58.
Usage
import uuid
import uuid58
s = "XDY9dmBbcMBXqcRvYw8xJ2"
# All of these return s:
uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
uuid58.encode("F4B247FD1F8745D4AA061C6FC0A8DFAF") # plain hex, any case
uuid58.encode(uuid.UUID("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"))
uuid58.encode(bytes.fromhex("f4b247fd1f8745d4aa061c6fc0a8dfaf"))
uuid58.encode(0xF4B247FD1F8745D4AA061C6FC0A8DFAF)
uuid58.decode(s) # 'f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'
uuid58.decode_uuid(s) # UUID('f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf')
uuid58.decode_bytes(s) # b'\xf4\xb2G\xfd\x1f\x87E\xd4...'
uuid58.decode_int(s) # 325257319917903217740243107280071483311
uuid58.is_uuid58("XDY9dmBbcMBXqcRvYw8xJ2") # True
uuid58.is_uuid58("zzzzzzzzzzzzzzzzzzzzzz") # False: exceeds 128 bits
uuid58.uuid58() # a random UUIDv4, encoded, e.g. 'Tj5D5H2Bc1LcPjwNNhH4xS'
Errors
All invalid-input errors subclass uuid58.Uuid58Error, which subclasses
ValueError. Each carries the spec error kind (SPEC.md Section 7) in kind,
an ErrorKind that compares equal to its spec name:
| Exception | kind |
Raised when |
|---|---|---|
InvalidLengthError |
"invalid_length" |
a string of the wrong length, or bytes whose length is not 16 |
InvalidCharacterError |
"invalid_character" |
a character not allowed in its position (incl. any non-ASCII) |
ValueOverflowError |
"overflow" |
a value outside 0..2**128 - 1 (decoded string or encoded int) |
try:
uuid58.decode(user_input)
except uuid58.InvalidCharacterError:
...
except uuid58.Uuid58Error as e:
print(e.kind) # invalid_length / overflow
Passing an unsupported type (for example bool, float or None) raises
TypeError. Error messages are not part of the specification and may change.
API
| Name | Description |
|---|---|
encode(value: UUIDLike) -> str |
Encode a UUID string, uuid.UUID, 16 bytes/bytearray, or int. |
decode(s: str) -> str |
Decode to the lowercase hyphenated UUID string. |
decode_uuid(s: str) -> uuid.UUID |
Decode to a uuid.UUID. |
decode_bytes(s: str) -> bytes |
Decode to 16 big-endian bytes (uuid.UUID.bytes order). |
decode_int(s: str) -> int |
Decode to an int in 0..2**128 - 1. |
is_uuid58(s: object) -> bool |
True exactly when decode(s) would succeed. Never raises. |
uuid58() -> str |
Generate a random UUIDv4 and return its encoding. |
ALPHABET, MAX_UUID58 |
The Base58 alphabet and the largest valid uuid58 string. |
Uuid58Error, ErrorKind, … |
See Errors. |
Accepted UUID strings
encode accepts exactly two textual forms, in any letter case (SPEC.md
Section 5.1):
- hyphenated, 36 characters:
f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf - plain, 32 hex digits:
f4b247fd1f8745d4aa061c6fc0a8dfaf
Everything else is rejected, including forms that uuid.UUID() accepts:
braces, the urn:uuid: prefix, misplaced hyphens and surrounding
whitespace. To encode those, parse them with uuid.UUID(...) first and pass
the resulting object.
bytes passed to encode are the 16 raw bytes of the UUID, never the ASCII
text of a UUID string.
Development
Uses uv (pinned via mise.toml).
uv run pytest # tests, including spec/vectors.json conformance
uv run ruff check # lint
uv run ruff format # format
uv run mypy # type check (strict)
The conformance tests read ../spec/vectors.json, so run them from a
checkout of the repository.
License
MIT
Metadata
Release files for uuid58 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uuid58-0.1.0.tar.gz | 7.3 kB | With provenance | Details for uuid58-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uuid58-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for uuid58-0.1.0-py3-none-any.whl |
Total release size: 15.0 kB
Release files / uuid58-0.1.0.tar.gz
| Download URL | uuid58-0.1.0.tar.gz |
|---|---|
| Size | 7.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d7c0da212b1c87237a435ee12f8fd39813b9634e43eadff692735fa2f2fde570
|
|
BLAKE2b-256 checksum How to use checksums |
2cfec095a42f890722e9dc21f1e0b07b9ec4267fc0237f98e549b3e85d55419d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / uuid58-0.1.0-py3-none-any.whl
| Download URL | uuid58-0.1.0-py3-none-any.whl |
|---|---|
| Size | 7.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5384ce73f7c6d351964f5c59ccb02f43a745a5a83368c54a78d61b6c816ba363
|
|
BLAKE2b-256 checksum How to use checksums |
6221c13d7fb0b301a10691f1fae9a1e0a8b6fffdd8f2c7d949ec625f3b471d5c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for uuid58 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for uuid58-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.