uuid

Updated March 13, 2026 · Modules

uuid uuid4 uuid1 uuid3 uuid5 guid identifier stdlib

The uuid module provides functions for generating universally unique identifiers (UUIDs) as specified in RFC 9562. UUIDs are 128-bit values that are practically guaranteed to be unique across different systems without requiring central coordination. The module supports multiple UUID versions: random (v4), time-based (v1, v6, v7), and namespace-based (v3, v5).

For most applications, uuid4() is the preferred choice since it generates cryptographically secure random UUIDs without exposing any system information.

Syntax

import uuid

Functions

uuid.uuid4()

Generates a random UUID using a cryptographically secure method.

uuid.uuid4()
# UUID('1f0799c0-98b9-433b-82eb-8c7fada847da')

Returns: A UUID object.

This is the most commonly used UUID function. The randomness makes it suitable for general-purpose unique identifiers where collision resistance matters more than determinism or ordering.

uuid.uuid1(node=None, clock_seq=None)

Generates a time-based UUID from a host ID, sequence number, and current time.

uuid.uuid1()
# UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

# With custom node and clock sequence
uuid.uuid1(node=0x001122334455, clock_seq=1234)
# UUID('12345678-1234-1234-1234-122334455')

Parameters:

Parameter	Type	Default	Description
`node`	`int`	`None`	A 48-bit positive integer representing the hardware address. If not provided, uses `getnode()`.
`clock_seq`	`int`	`None`	A 14-bit positive integer for the clock sequence. If not provided, a random value is generated.

Returns: A UUID object.

This function embeds the machine’s network address in the UUID, which can compromise privacy. It also exposes when the UUID was created due to the timestamp encoding.

uuid.uuid3(namespace, name)

Generates a UUID based on the MD5 hash of a namespace identifier and a name.

uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
# UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

uuid.uuid3(uuid.NAMESPACE_URL, 'https://example.com/page')
# UUID('c5aef73c-3b0a-3dc1-a7b2-8c3d4e5f6a7b')

Parameters:

Parameter	Type	Default	Description
`namespace`	`UUID`	—	A predefined namespace UUID (e.g., `uuid.NAMESPACE_DNS`, `uuid.NAMESPACE_URL`)
`name`	`str`	—	A string to hash. Will be encoded as UTF-8.

Returns: A UUID object.

Example with all namespaces:

# NAMESPACE_DNS - for fully qualified domain names
uuid.uuid3(uuid.NAMESPACE_DNS, 'example.com')
# UUID('e5c3b0a3-5e9f-3c8a-9f1b-2d4c6e8f0a1b')

# NAMESPACE_URL - for URLs
uuid.uuid3(uuid.NAMESPACE_URL, 'https://example.com')
# UUID('c4c9a2b1-8d7e-3f4c-9a2b-1c3d5e7f9a0b')

# NAMESPACE_OID - for ISO OIDs
uuid.uuid3(uuid.NAMESPACE_OID, '1.2.3.4')
# UUID('7f6e5d4c-3b2a-1c0d-9e8f-7a6b5c4d3e2f')

# NAMESPACE_X500 - for X.500 DNs
uuid.uuid3(uuid.NAMESPACE_X500, 'cn=test,dc=example,dc=com')
# UUID('2a1b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')

The same namespace and name always produce the same UUID, making this useful for generating deterministic identifiers.

uuid.uuid5(namespace, name)

Generates a UUID based on the SHA-1 hash of a namespace identifier and a name.

uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
# UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

Parameters:

Parameter	Type	Default	Description
`namespace`	`UUID`	—	A predefined namespace UUID
`name`	`str`	—	A string to hash. Will be encoded as UTF-8.

Returns: A UUID object.

This is similar to uuid3() but uses SHA-1 instead of MD5. SHA-1 produces a longer hash (160-bit vs 128-bit), reducing collision risk. However, MD5 is still widely used for namespace-based UUIDs due to historical compatibility.

uuid.uuid7()

Generates a time-based UUID according to RFC 9562 with embedded timestamp and counter for monotonicity.

uuid.uuid7()
# UUID('0192c3e0-9b1e-7c0d-a123-4567890abcde')

import datetime
u = uuid.uuid7()
datetime.datetime.fromtimestamp(u.time / 1000)
# datetime.datetime(2026, 3, 10, 12, 0, 0, 123456)

Returns: A UUID object.

UUIDv7 encodes a 48-bit timestamp in milliseconds since Unix epoch, followed by a counter to guarantee monotonicity within each millisecond. This is ideal for database primary keys where time-ordered IDs improve index performance.

uuid.getnode()

Gets the hardware address as a 48-bit positive integer.

uuid.getnode()
# 32981763405401

# Convert to MAC address format
mac = uuid.getnode()
':'.join(f'{(mac >> i) & 0xff:02x}' for i in range(40, -1, -8))
# '02:00:00:00:00:00'

Returns: A 48-bit positive integer representing the MAC address.

On the first call, this may be slow as it launches a subprocess to detect the hardware address. If no MAC address can be obtained, a random 48-bit number with the multicast bit set is returned.

Predefined Namespaces

These UUID objects are used with uuid3() and uuid5() to generate deterministic namespaced UUIDs:

Constant	Description
`uuid.NAMESPACE_DNS`	For fully qualified domain names
`uuid.NAMESPACE_URL`	For URLs
`uuid.NAMESPACE_OID`	For ISO object identifiers
`uuid.NAMESPACE_X500`	For X.500 Distinguished Names

Special UUID Values

Constant	Description
`uuid.NIL`	UUID with all 128 bits set to zero
`uuid.MAX`	UUID with all 128 bits set to one

uuid.NIL
# UUID('00000000-0000-0000-0000-000000000000')

uuid.MAX
# UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

UUID Object Attributes

Once you have a UUID object, you can access various properties:

u = uuid.uuid4()

u.hex        # '1f0799c098b9433b82eb8c7fada847da'
u.int        # 236345678901234567890123456789012345
u.bytes      # b'\x1f\x07\x99\xc0\x98\xb9\x43\x3b\x82\xeb\x8c\x7f\xad\xa8G\xda'
str(u)       # '1f0799c0-98b9-433b-82eb-8c7fada847da'
u.version    # 4
u.variant    # 'RFC_4122'

Common Patterns

Generating unique IDs for database records

import uuid

# Simple unique ID
user_id = uuid.uuid4()
print(user_id)
# UUID('1f0799c0-98b9-433b-82eb-8c7fada847da')

# As a string for storage
user_id_str = str(uuid.uuid4())
# '1f0799c0-98b9-433b-82eb-8c7fada847da'

Namespace-based stable identifiers

Generate the same UUID for the same input, useful for caching or deduplication:

# Same input always produces same UUID
cache_key = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/api/users')
print(cache_key)
# UUID('a3f2b1c0-5d4e-6f78-9012-3456789abcde')

# Verify it's deterministic
uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/api/users') == cache_key
# True

Time-ordered IDs for databases

UUIDv7 provides time-ordered IDs that improve database index locality:

# Generate IDs in rough time order
ids = [uuid.uuid7() for _ in range(3)]
# These will sort roughly by creation time

# Extract timestamp
import datetime
u = uuid.uuid7()
dt = datetime.datetime.fromtimestamp(u.time / 1000)
print(dt)
# 2026-03-10 12:00:00.123456

Converting between formats

# From string
u = uuid.UUID('1f0799c0-98b9-433b-82eb-8c7fada847da')

# From bytes
u = uuid.UUID(bytes=b'\x1f\x07\x99\xc0\x98\xb9\x43\x3b\x82\xeb\x8c\x7f\xad\xa8G\xda')

# From integer
u = uuid.UUID(int=0x1f0799c098b9433b82eb8c7fada847da)

# Convert back to different formats
u.hex        # '1f0799c098b9433b82eb8c7fada847da'
u.bytes      # b'\x1f\x07\x99\xc0...'
u.int        # 236345678901234567890123456789012345
u.urn        # 'urn:uuid:1f0799c0-98b9-433b-82eb-8c7fada847da'

Syntax

Functions

uuid.uuid4()

uuid.uuid1(node=None, clock_seq=None)

uuid.uuid3(namespace, name)

uuid.uuid5(namespace, name)

uuid.uuid7()

uuid.getnode()

Predefined Namespaces

Special UUID Values

UUID Object Attributes

Common Patterns

Generating unique IDs for database records

Namespace-based stable identifiers

Time-ordered IDs for databases

Converting between formats

See Also