UUID in Python

What is a UUID in Python

Import the uuid module and you have four generators on every supported Python: uuid4() (random, the usual choice for a primary key), uuid1() (time plus the machine's node address — it can leak a MAC address and it exposes when the value was created), and the deterministic pair uuid3() and uuid5(), which hash a namespace and a name with MD5 or SHA-1.

Python 3.14 added the RFC 9562 versions: uuid6(), uuid7() and uuid8(), plus the uuid.NIL and uuid.MAX constants and a --count option for the module's command line. v7 is the one most projects want for new tables: it embeds a 48-bit Unix millisecond timestamp and a counter, so identifiers sort by creation order and inserts do not scatter across the index. On an older interpreter, the uuid6 package or uuid-utils fills the same gap.

How to

1. Import the module and call uuid.uuid4() — this is enough for most code.
2. On Python 3.14+, use uuid.uuid7() when the values will be stored in an indexed column.
3. Use uuid.uuid5(namespace, name) when the same input has to map to the same UUID on every machine.

Use cases

• Database primary keys: v4 for random keys, v7 when the table is large and insert order matters.
• Idempotent pipelines: a v5 derived from a URL or a business key makes reruns produce the same row id.
• Test fixtures: deterministic ids keep assertions stable between runs.

Compare UUID in Python with other formats

Code examples

Random (any version)

import uuid

print(uuid.uuid4())                 # 550e8400-e29b-41d4-a716-446655440000
print(str(uuid.uuid4()), uuid.uuid4().hex, sep='\n')

# A list of ids for bulk inserts
ids = [str(uuid.uuid4()) for _ in range(1000)]

Time-ordered (Python 3.14+)

import uuid

print(uuid.uuid7())        # 019535d9-3df7-79fb-b466-fa907fa17f9e
print(uuid.uuid6())        # reordered v1
print(uuid.NIL, uuid.MAX)  # nil and max UUID constants

Deterministic from a name

import uuid

# The same pair always yields the same UUID, on any machine
uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/page')

# uuid3() is the MD5-based, legacy equivalent

Command line

# Python 3.12+: run the module directly
python -m uuid

# Python 3.14+: pick a version and a count
python -m uuid -u uuid7 -C 5

Frequently asked questions