uuid

import uuid

Provides RFC 9562 (and RFC 4122) compliant Universally Unique Identifier (UUID) generation, parsing, validation, and inspection.

A UUID is a 128-bit label represented as 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens in the form:

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

where M encodes the version and N encodes the variant.

Supported versions

The Nil UUID (00000000-0000-0000-0000-000000000000) and the Max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff) are also defined as per RFC 9562.

Note: UUID v2 (DCE Security) is intentionally omitted. RFC 9562 declares v2 “out of scope”, and its specification lives in a separate DCE document rather than in the IETF UUID standard.

Quick start

import uuid

echo uuid.v4()           # e.g. '110e8400-e29b-41d4-a716-446655440000'
echo uuid.v7()           # time-ordered, database-friendly
echo uuid.is_valid('...')

var id = uuid.UUID('110e8400-e29b-41d4-a716-446655440000')
echo id.version()          # 4
echo id.variant()          # 'RFC 9562'
echo id.urn()            # 'urn:uuid:110e8400-...'

Namespace UUIDs (for v3 / v5)

RFC 9562 §Appendix C pre-defines four namespace UUIDs:

• uuid.NAMESPACE_DNS: for fully-qualified domain names - uuid.NAMESPACE_URL: for URLs - uuid.NAMESPACE_OID: for ISO OIDs - uuid.NAMESPACE_X500: for X.500 distinguished names

The uuid API

Every public name in uuid, wherever it is declared. Each links to the page that documents it.

Constants

NAMESPACE_DNS

uuid.NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'

Pre-defined namespace UUID for fully-qualified domain names (FQDN). Use with uuid.v3() or uuid.v5() when the name is a DNS hostname.

Value: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

NAMESPACE_URL

uuid.NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'

Pre-defined namespace UUID for URLs. Use with uuid.v3() or uuid.v5() when the name is a URL.

Value: 6ba7b811-9dad-11d1-80b4-00c04fd430c8

NAMESPACE_OID

uuid.NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8'

Pre-defined namespace UUID for ISO Object Identifiers (OID). Use with uuid.v3() or uuid.v5() when the name is an ISO OID.

Value: 6ba7b812-9dad-11d1-80b4-00c04fd430c8

NAMESPACE_X500

uuid.NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8'

Pre-defined namespace UUID for X.500 Distinguished Names. Use with uuid.v3() or uuid.v5() when the name is an X.500 DN.

Value: 6ba7b814-9dad-11d1-80b4-00c04fd430c8

NIL

uuid.NIL = '00000000-0000-0000-0000-000000000000'

The Nil UUID: all 128 bits are zero. Defined in RFC 9562 §5.9 as a special UUID that signifies “no value”.

Value: 00000000-0000-0000-0000-000000000000

MAX

uuid.MAX = 'ffffffff-ffff-ffff-ffff-ffffffffffff'

The Max UUID: all 128 bits are one. Defined in RFC 9562 §5.10 as a special UUID often used as a sentinel upper-bound in range queries.

Value: ffffffff-ffff-ffff-ffff-ffffffffffff

Functions

is_valid()

uuid.is_valid(str) -> bool

Returns true if str is a syntactically valid UUID in canonical form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), case-insensitive.

This function checks only the structure and character set; it does not verify that the version and variant bits are set to any particular value, so the Nil and Max UUIDs are considered valid.

Example

import uuid

uuid.is_valid('f47ac10b-58cc-4372-a567-0e02b2c3d479') # true
uuid.is_valid('not-a-uuid')                           # false
uuid.is_valid(uuid.NIL)                               # true

Parameters

• str (string) — The string to test.

Returns bool

version()

uuid.version(str: string) -> number

Returns the version number (1–8) of a UUID string, or nil if the UUID is the Nil or Max special form, or if str is not a valid UUID.

Parameters

• str (string) — A canonical UUID string.

Returns number — | nil

v1()

uuid.v1(node: ?string, clock_seq: ?number) -> string

Generates a UUID Version 1 (time-based) as defined in RFC 4122 §4.1 / RFC 9562 §5.1.

A v1 UUID encodes a 60-bit timestamp counted in 100-nanosecond intervals since the Gregorian epoch (1582-10-15 00:00:00 UTC), a 14-bit clock sequence, and a 48-bit node identifier (MAC address or random).

Privacy note: v1 UUIDs embed timing and node information. For privacy-sensitive contexts prefer v4() or v7().

Example

import uuid
echo uuid.v1()  # e.g. '6ba7b810-9dad-11d1-80b4-00c04fd430c8'

Parameters

• | (string) — nil node Optional 12-char hex string for the node field (48-bit MAC address). If nil, a random multicast node value is used (RFC 4122 §4.5).
• | (number) — nil clock_seq Optional 14-bit clock sequence (0–16383). If nil, the internal monotonic sequence is used.

Returns string — Canonical UUID string.

v3()

uuid.v3(namespace: string, name: string) -> string

Generates a UUID Version 3 (name-based, MD5) as defined in RFC 4122 §4.3 / RFC 9562 §5.3.

Given the same namespace and name, v3() always returns the same UUID. The UUID is derived by computing the MD5 hash of the namespace UUID bytes concatenated with the UTF-8 encoded name bytes, then setting the version and variant bits.

Note: MD5 is cryptographically broken. For new designs, prefer v5() (SHA-1) or generate random UUIDs with v4().

Example

import uuid

echo uuid.v3(uuid.NAMESPACE_DNS, 'www.example.com')
# always: '5df41881-3aed-3515-88a7-2f4a814cf09e'

Parameters

• namespace (string) — A UUID string to use as the namespace. Use the pre-defined NAMESPACE_* constants or any other valid UUID.
• name (string) — The name within the namespace.

Returns string — Canonical UUID string.

Raises Error If namespace is not a valid UUID.

v4()

uuid.v4() -> string

Generates a UUID Version 4 (random) as defined in RFC 4122 §4.4 / RFC 9562 §5.4.

122 bits are filled with pseudo-random data; the remaining 6 bits encode the version (0100) and variant (10).

This is the most commonly used UUID version for general-purpose unique identifiers where time-ordering is not required.

Example

import uuid

echo uuid.v4()  # e.g. 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

Returns string — Canonical UUID string.

v5()

uuid.v5(namespace: string, name: string) -> string

Generates a UUID Version 5 (name-based, SHA-1) as defined in RFC 4122 §4.3 / RFC 9562 §5.5.

Identical in structure to v3() but uses SHA-1 instead of MD5. SHA-1 is preferred over MD5 for new name-based UUIDs. Only the first 128 bits of the 160-bit SHA-1 digest are used.

Given the same namespace and name, v5() always returns the same UUID.

Example

import uuid

echo uuid.v5(uuid.NAMESPACE_URL, 'https://www.example.com')
# always: 'a0787afd-c170-5773-8d60-02739168de9f'

Parameters

• namespace (string) — A UUID string to use as the namespace. Use the pre-defined NAMESPACE_* constants or any other valid UUID.
• name (string) — The name within the namespace.

Returns string — Canonical UUID string.

Raises Error If namespace is not a valid UUID.

v6()

uuid.v6(node: ?string, clock_seq: ?number) -> string

Generates a UUID Version 6 (time-ordered) as defined in RFC 9562 §5.6.

v6 is a reordered variant of v1 that places the most significant timestamp bits first, making v6 UUIDs naturally sortable lexicographically by generation time. It retains the same 60-bit Gregorian timestamp, 14-bit clock sequence, and 48-bit node as v1.

v6 is the recommended replacement for v1 when time-ordered, monotonic IDs derived from a Gregorian clock are required. For most new designs, v7() (Unix-time based) is simpler and equally sortable.

Example

import uuid

echo uuid.v6()  # e.g. '1ef9e292-a7a4-6000-80b4-00c04fd430c8'

Parameters

• | (string) — nil node Optional 12-char hex node (see v1()).
• | (number) — nil clock_seq Optional 14-bit clock sequence (see v1()).

Returns string — Canonical UUID string.

v7()

uuid.v7() -> string

Generates a UUID Version 7 (Unix-time ordered) as defined in RFC 9562 §5.7.

v7 UUIDs embed a 48-bit Unix millisecond timestamp in the most significant bits, followed by a 12-bit sub-millisecond sequence counter (for monotonicity within the same millisecond) and 62 random bits for uniqueness.

v7 is the recommended version for new systems that need:

• Time-ordered, lexicographically sortable identifiers. - Good database index locality (avoids B-tree fragmentation). - No MAC address leakage (unlike v1 / v6).

Example

import uuid

echo uuid.v7()  # e.g. '018f5e1a-2b3c-7d4e-9f0a-1b2c3d4e5f6a'

Layout (RFC 9562 §5.7):

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           unix_ts_ms                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |       rand_a          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Returns string — Canonical UUID string.

v8()

uuid.v8(a: number, b: number, c: number) -> string

Generates a UUID Version 8 (custom / application-defined) as defined in RFC 9562 §5.8.

v8 is intended for vendor-specific or experimental use cases where the caller needs to embed application-defined data into a UUID while retaining the standard format, version, and variant bits. RFC 9562 does not prescribe the meaning of any field beyond the version and variant.

The three parameters together provide 48 + 12 + 62 = 122 bits of application-controlled data.

Example

import uuid

# Embed a shard ID (a), a type tag (b), and a sequence number (c).
echo uuid.v8(0x0123456789ab, 0x0cd, 0x0123456789abcdef)

Parameters

• a (number) — 48-bit application-defined field (bits 0–47). Values exceeding 48 bits are silently truncated.
• b (number) — 12-bit application-defined field (bits 48–59). Values exceeding 12 bits are silently truncated.
• c (number) — 62-bit application-defined field (bits 64–125). Values exceeding 62 bits are silently truncated.

Returns string — Canonical UUID string.

nil_uuid()

uuid.nil_uuid() -> string

Returns the pre-defined Nil UUID string.

Equivalent to the module-level constant uuid.NIL. Provided as a function for symmetry with the other generators.

Returns string — '00000000-0000-0000-0000-000000000000'

max_uuid()

uuid.max_uuid() -> string

Returns the pre-defined Max UUID string.

Equivalent to the module-level constant uuid.MAX. Provided as a function for symmetry with the other generators.

Returns string — 'ffffffff-ffff-ffff-ffff-ffffffffffff'

parse()

uuid.parse(str: string) -> UUID

Parses a UUID string (in canonical, raw hex, URN, or brace-wrapped form) and returns a UUID object.

This is equivalent to calling UUID(str) directly.

Example

import uuid

var id = uuid.parse('urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479')
echo id.version()   # 4

Parameters

• str (string) — The UUID string to parse.

Returns UUID

Raises Error If str is not a recognisable UUID form.

from_bytes()

uuid.from_bytes(bytes_list: list|bytes) -> string

Converts a list of 16 byte integers (0–255) in big-endian order into a canonical UUID string.

Parameters

• bytes_list (list) — A list of exactly 16 integers in [0, 255].

Returns string — Canonical UUID string.

Raises Error If bytes_list does not contain exactly 16 bytes.

from_int()

uuid.from_int(int_val) -> string

Converts an integer value (the numeric representation of a 128-bit UUID, as returned by UUID.int()) into a canonical UUID string.

Accepts either a bigint (the exact way to represent a full 128-bit value, and what UUID.int() itself returns) or a plain number for a small value that’s within safe integer precision (e.g. from_int(0)).

Parameters

• int_val (number|bigint) — The integer value of the UUID.

Returns string — Canonical UUID string.

Classes

UUID

class uuid.UUID

Represents a parsed, immutable UUID value.

Instances expose the canonical string form plus convenience properties and methods for inspecting and converting the UUID.

Example

import uuid

var id = uuid.UUID('f47ac10b-58cc-4372-a567-0e02b2c3d479')
echo id.version()   # 4
echo id.variant()   # 'RFC 9562'
echo id.urn()     # 'urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479'
echo id.hex()     # 'f47ac10b58cc4372a5670e02b2c3d479'
echo id.int()     # integer value of the 128-bit UUID

Raises Error if the supplied string is not a valid UUID.

Fields

Constructor

uuid.UUID(uuid_str: string)

Creates a new UUID object from a canonical UUID string.

The constructor normalises the input to lowercase and accepts any of the following common forms:

• xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (canonical, with hyphens) - xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (raw hex, no hyphens) - urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (URN form) - {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} (brace-wrapped GUID form)

Parameters

• uuid_str (string) — The UUID to parse.

Raises Error If uuid_str is not a valid UUID in any accepted form.

UUID.version()

uuid.UUID.version()

Returns the UUID version number (1–8), or nil for the Nil and Max special-form UUIDs which carry no version.

The version is encoded in the high nibble of byte 6 (the M position in the canonical format xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx).

UUID.variant()

uuid.UUID.variant()

Returns a human-readable string describing the UUID variant field.

The variant occupies the high bits of byte 8 (the N position):

UUID.to_string()

uuid.UUID.to_string() -> string

Returns the string representation of the UUID in canonical lowercase hyphenated form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Returns string

UUID.urn()

uuid.UUID.urn() -> string

Returns the UUID as a URN string per RFC 9562 §4: urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Returns string

UUID.hex()

uuid.UUID.hex() -> string

Returns the raw 32-character lowercase hex representation of the UUID with all hyphens removed.

Returns string

UUID.int()

uuid.UUID.int() -> bigint

Returns the UUID as an integer (the numeric value of its 128 bits), as an exact bigint: a 128-bit value is always far beyond what a regular number can represent exactly, so this never uses one. Pass the result straight to from_int() to convert back.

Returns bigint

UUID.bytes()

uuid.UUID.bytes() -> list

Returns the UUID as a 16-element list of byte values (integers 0–255), in big-endian (network) byte order.

Returns list

UUID.is_nil()

uuid.UUID.is_nil() -> bool

Returns true if this UUID is the Nil UUID (00000000-0000-0000-0000-000000000000).

Returns bool

UUID.is_max()

uuid.UUID.is_max() -> bool

Returns true if this UUID is the Max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff).

Returns bool

UUID.equals()

uuid.UUID.equals(other) -> bool

Compares this UUID with another UUID or canonical UUID string. Returns true if both UUIDs represent the same 128-bit value.

Parameters

• | (UUID) — string other The UUID to compare against.

Returns bool

Raises TypeError if other is neither a UUID nor a string.

UUID.compare()

uuid.UUID.compare(other: instance) -> number

Compares this UUID with another UUID lexicographically by canonical string form. For time-ordered versions (v1, v6, v7) this is also a comparison by generation time.

Parameters

• other (UUID)

Returns number — A negative number if this UUID sorts before other, a positive number if after, 0 if they’re equal.

2026, Richard Ore and The Zuri Contributors