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.
import uuid user_id = uuid.uuid4() print(user_id.version) # 4 print(str(user_id)) # something like 3f0c... (random)
Try it
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.
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.dumpscannot encode aUUIDdirectly. - 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
uuid4is unguessable in practice, but do not use UUIDs as passwords or session tokens when you need explicit guarantees; use thesecretsmodule. - Random UUIDs as database primary keys scatter inserts across an index. Time-ordered
uuid7()(3.14+) keeps new rows near each other. uuid5takes astrname (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, raisesTypeError; bad text raisesValueError. - Immutable. Assigning to an attribute raises
TypeError. - Command line. Since Python 3.12,
python -m uuidprints a new UUID.
Related
secrets,hashlib,random,base64- Lessons: Math and random, Data types