Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Math, Data and Text

The uuid module

Reference for Python's uuid module: generate random and name-based UUIDs, parse and format them, read fields and versions, and choose the right version.

The uuid module creates and handles universally unique identifiers (UUIDs): 128-bit values usually written as 32 hexadecimal digits in five groups, like 12345678-1234-5678-1234-567812345678. Two systems can generate UUIDs independently without coordinating and still, for practical purposes, never collide. That makes them popular as database keys, file names and request IDs.

The most used functions are uuid4() (random) and uuid5() (a repeatable ID derived from a namespace and a name). All of them return a UUID object, which is immutable, hashable and comparable.

Python
import uuid

user_id = uuid.uuid4()
print(user_id.version)    # 4
print(str(user_id))       # something like 3f0c... (random)

Try it

Python Name-based UUIDs and UUID objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Random IDs, uses and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Main members

Name Description
uuid.uuid4() A random UUID (version 4) from the operating system's secure random source. The usual choice.
uuid.uuid5(namespace, name) A repeatable UUID from a SHA-1 hash of name within namespace (name is a str).
uuid.uuid3(namespace, name) Like uuid5 but with MD5. Prefer uuid5.
uuid.uuid1() Based on host ID and the current time. Can reveal the machine; use with care.
uuid.uuid6(), uuid7(), uuid8() Time-ordered and custom layouts (Python 3.14+). uuid7 sorts by creation time, which suits database keys.
uuid.UUID(hex=None, bytes=None, int=None, fields=None, version=None) Builds an object from exactly one of these representations.
uuid.NAMESPACE_DNS, NAMESPACE_URL, NAMESPACE_OID, NAMESPACE_X500 Predefined namespaces for uuid3 / uuid5.
uuid.NIL, uuid.MAX The all-zero and all-one UUIDs (Python 3.14+).

UUID attributes

Attribute Value
str(u) The standard hyphenated lowercase form.
u.hex 32 hexadecimal digits, no hyphens.
u.int The 128-bit integer.
u.bytes 16 bytes, big-endian.
u.urn "urn:uuid:...".
u.version, u.variant Version number (or None for non-RFC variants) and variant string.
u.fields Six-field tuple (time_low, time_mid, ...).
u.is_safe Whether uuid1 created it in a multiprocessing-safe way (SafeUUID).

Usage notes

  • UUIDs are objects, not strings. Convert with str(u) when writing to JSON, SQL or URLs. json.dumps cannot encode a UUID directly.
  • Compare UUIDs with == on objects, or normalize strings (uuid.UUID(text)), because the same ID can appear in uppercase, with braces, or without hyphens.
  • Not secrets. A uuid4 is unguessable in practice, but do not use UUIDs as passwords or session tokens when you need explicit guarantees; use the secrets module.
  • Random UUIDs as database primary keys scatter inserts across an index. Time-ordered uuid7() (3.14+) keeps new rows near each other.
  • uuid5 takes a str name (encode your own data first if it is bytes). Pick a namespace once and keep it for the life of the data.
  • The constructor accepts one representation only. uuid.UUID() with none, or with two, raises TypeError; bad text raises ValueError.
  • Immutable. Assigning to an attribute raises TypeError.
  • Command line. Since Python 3.12, python -m uuid prints a new UUID.