Skip to main content

uuid58 for Python

PyPI CI License: MIT

Shorten UUIDs to 22-character Base58 strings, and back, in Python. Works with uuid.UUID from the standard library, as well as strings, bytes, and ints.

f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf  ⇄  XDY9dmBbcMBXqcRvYw8xJ2
  • Fixed 22 characters, using the Bitcoin Base58 alphabet: URL-safe, with no 0, O, I, or l.
  • Sortable: sorting uuid58 strings by code point sorts the UUIDs numerically, so UUIDv7 IDs stay time-ordered.
  • Stable spec, well tested: implements uuid58 spec 1.1.0 and passes its 200+ shared test vectors, so output matches every other language.
  • No dependencies, fully typed (py.typed), CPython 3.10+.

Try it in your browser · Specification · Other languages

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.

Compatibility

This package implements uuid58 spec 1.1.0 and passes every case in spec/vectors.json in CI. A string encoded here decodes to the same UUID with every other uuid58 implementation, and the reverse.

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. See LICENSE.

Metadata

Release files for uuid58 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uuid58 0.1.1
File Size Uploaded Provenance Actions
uuid58-0.1.1.tar.gz 7.7 kB With provenance Details for uuid58-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uuid58 0.1.1
File Interpreter ABI Platform Actions
uuid58-0.1.1-py3-none-any.whl Python 3 none any Details for uuid58-0.1.1-py3-none-any.whl

Total release size: 15.7 kB

Release files / uuid58-0.1.1.tar.gz

Download URL uuid58-0.1.1.tar.gz
Size 7.7 kB
Tags Source
SHA-256 checksum
How to use checksums
fa6cd8daf1e190c92136abb082167a18d40a9e5c2b6869dd4714b2c71d418349
BLAKE2b-256 checksum
How to use checksums
9e315bb110204e8e083f32fdcfdad1bae00592b90be9e99fb2bfaa1051b0bf55
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 17, 2026.

Transparency log

Release files / uuid58-0.1.1-py3-none-any.whl

Download URL uuid58-0.1.1-py3-none-any.whl
Size 8.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fbe94c19641cf1d36c796a4d60344e1b1e6fcacc905da0d3efe87454298e04a9
BLAKE2b-256 checksum
How to use checksums
ea550a2a606797fcb93f56249e1dd017b85f1bf5d13ed59ad1bff2ec01799761
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 17, 2026.

Transparency log

Security for uuid58 0.1.1

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.

Select from 2 files

Attestation for uuid58-0.1.1.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 17, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page