`uuid`

The Python uuid module provides a way to generate universally unique identifiers (UUIDs), which are 128-bit values used to uniquely identify information in computer systems. UUIDs are often used when a unique identifier is required, such as database keys or session IDs.

Here’s a quick example:

>>> import uuid

>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

Key Features

Generates UUIDs using random, time-based, and name-based methods
Supports UUID versions 1, 3, 4, 5, 6, 7, and 8 as specified in RFC 9562, which supersedes RFC 4122 and leaves version 2 outside its scope
Parses and validates UUID strings and objects
Converts UUIDs to and from string representations
Integrates seamlessly with Python types and serialization
Runs as a command-line tool with python -m uuid to generate one or more UUIDs of any supported version
Designed to be unique across space and time, as intended by RFC 9562

Frequently Used Classes and Functions

Object	Type	Description
`uuid.UUID`	Class	Represents a UUID object
`uuid.uuid1()`	Function	Generates a UUID based on the host ID and current time
`uuid.uuid3()`	Function	Generates a name-based UUID using MD5 hashing
`uuid.uuid4()`	Function	Generates a random UUID
`uuid.uuid5()`	Function	Generates a name-based UUID using SHA-1 hashing
`uuid.uuid6()`	Function	Generates a time-ordered UUID as an alternative to `uuid1()` (added in Python 3.14)
`uuid.uuid7()`	Function	Generates a time-ordered UUID from a Unix timestamp in milliseconds and random bits (added in Python 3.14)
`uuid.uuid8(a=None, b=None, c=None)`	Function	Generates a UUID from up to three optional user-supplied integer fields for custom layouts, filling any omitted field with random bits, added in Python 3.14
`uuid.getnode()`	Function	Returns the hardware address as a 48-bit integer
`uuid.NAMESPACE_DNS`	Constant	Represents the DNS namespace constant for name-based UUIDs
`uuid.NIL`	Constant	Represents the Nil UUID, with all 128 bits set to zero, added in Python 3.14
`uuid.MAX`	Constant	Represents the Max UUID, with all 128 bits set to one, added in Python 3.14

The version you pick decides how those 128 bits get filled, so calling the same function twice can hand you two unrelated values, two values that sort, or the very same value twice:

Only the name-based versions repeat, which is what makes them reproducible across machines and runs.

Examples

Generating a name-based UUID using MD5 hashing:

>>> import uuid

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

Common Use Cases

Generating unique identifiers for database entries
Creating unique session IDs for web applications
Ensuring uniqueness of identifiers in distributed systems
Tagging files, resources, or objects with unique IDs
Safely merging data from multiple sources
Implementing resource identifiers in network protocols
Supporting object tracking in logging or auditing systems

Real-World Example

Here’s an example of using the uuid module to generate a unique filename for an uploaded file in a web application. This approach helps prevent filename collisions:

>>> import uuid

>>> def generate_unique_filename(filename):
...     file_extension = filename.split(".")[-1]
...     unique_id = uuid.uuid4()
...     return f"{unique_id}.{file_extension}"
...

>>> generate_unique_filename("document.txt")
'3f6d2f0e-19a4-4e5b-8cb3-3c9b7f2c9db7.txt'

In this example, the uuid module generates a UUID to ensure that each uploaded file has a unique name, preventing any potential file overwrites.

Tutorial

Serialize Your Data With Python

In this in-depth tutorial, you'll explore the world of data serialization in Python. You'll compare and use different data serialization formats, serialize Python objects and executable code, and handle HTTP message payloads.

intermediate data-science web-dev

For additional information on related topics, take a look at the following resources: