Skip to main content

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)

Source distribution for uuid58 0.1.0
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)

Table of built distributions (wheels) for uuid58 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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