Python uuid Module: Syntax, Usage, and Examples

The uuid module helps you generate UUIDs, short for “Universally Unique Identifiers,” which are values designed to be extremely unlikely to collide. You’ll often use UUIDs as IDs for users, orders, files, sessions, or anything that needs a reliable unique label.

How to Use the uuid Module

You import the uuid module, then call one of its UUID generator functions like uuid4().

import uuid

new_id = uuid.uuid4()
print(new_id)

That prints something like:

7c5f6c52-1f1d-4c8e-9a2a-4bfa9dfe2c9d

A UUID is a real Python object, not just a string. You can convert it to a string when you want to store it or send it over the network.

import uuid

user_id = uuid.uuid4()
user_id_str =str(user_id)

print(user_id_str)
print(type(user_id))
print(type(user_id_str))

The uuid module is part of Python’s standard library, so you can use it without installing anything extra.

Common UUID generators

The uuid module gives you multiple ways to generate identifiers, and each one has a different “source” for its randomness or uniqueness.

import uuid

print(uuid.uuid1())# time + device info
print(uuid.uuid3(uuid.NAMESPACE_DNS,"mimo.org"))# name-based (MD5)
print(uuid.uuid4())# random
print(uuid.uuid5(uuid.NAMESPACE_DNS,"mimo.org"))# name-based (SHA-1)

You won’t use all of these every day, but they’re useful in different situations, especially if you need consistent IDs from the same input.

Python’s UUID behavior follows rfc4122, which is the widely used specification for how these identifiers are structured.

When to Use the uuid Module

The uuid module shines anytime you need an ID that is safe to generate without asking a database for permission first.

1) Creating IDs for database records

Auto-increment IDs like 1, 2, 3 are simple, but they can leak information like how many users you have. UUIDs don’t tell that story.

You can generate a UUID before inserting a record:

import uuid

order = {
"id":str(uuid.uuid4()),
"status":"pending"
}

2) Generating safe filenames

If users upload files, two people can upload profile.png and one upload overwrites the other. UUIDs solve that.

import uuid

filename =f"{uuid.uuid4()}.png"
print(filename)

3) Creating tokens for links and sessions

Password reset links, invite links, email verification links, all of these need “unguessable” values. UUIDs are a solid option for that.

import uuid

reset_token = uuid.uuid4().hex
print(reset_token)

That .hex version removes the dashes and gives you a clean string.

4) Creating stable identifiers from names

Sometimes you want the same input to always produce the same output. That’s where name-based UUIDs help.

Example: generating an ID for a product category name.

import uuid

category_name ="winter-jackets"
category_id = uuid.uuid5(uuid.NAMESPACE_URL, category_name)

print(category_id)

You’ll get the same UUID every time you run that with the same namespace and string.

Examples of the uuid Module

Here are a few practical examples that show how UUIDs fit into real projects.

Example 1: Assigning UUIDs to users in a simple app

Imagine a small Python app that keeps user data in memory.

import uuid

users = []

defcreate_user(name):
    user = {
"id":str(uuid.uuid4()),
"name": name
    }
    users.append(user)
return user

print(create_user("Amina"))
print(create_user("Leo"))

Now each user has a unique ID that won’t conflict with anyone else.

Example 2: Using UUIDs as dictionary keys

UUID strings make great keys in dictionaries, especially when you store objects by ID.

import uuid

messages = {}

msg_id =str(uuid.uuid4())
messages[msg_id] = {"text":"Hi there!","read":False}

print(messages[msg_id])

This pattern shows up in caching, storing temporary sessions, and in-memory queues.

Example 3: Creating a unique upload path

Here’s a common pattern when storing uploads by date and a UUID.

import uuid
from datetimeimport date

today = date.today().isoformat()
file_path =f"uploads/{today}/{uuid.uuid4()}.jpg"

print(file_path)

If you later move to cloud storage, the same idea still works.

Example 4: Generating the same ID from the same input

Name-based UUIDs are predictable in a good way. Great for things like syncing data across systems.

import uuid

namespace = uuid.NAMESPACE_DNS
project_name ="demo-project"

project_id_1 = uuid.uuid5(namespace, project_name)
project_id_2 = uuid.uuid5(namespace, project_name)

print(project_id_1)
print(project_id_2)
print(project_id_1 == project_id_2)

This prints the same value twice, and the final line is True.

Learn More About the uuid Module

UUIDs look simple, but a few details matter if you want to use them well.

UUID versions explained (quick and practical)

The version is the “strategy” used to create the UUID.

• UUID1: based on time and hardware-related data
• UUID3: name-based using MD5 hashing
• UUID4: random, most common choice
• UUID5: name-based using SHA-1 hashing

In most apps, uuid4() is the default pick because it’s random and easy.

With version 1 UUIDs, part of the value comes from a timestamp, and part may come from machine-specific information.

Using .hex for cleaner strings

The normal string version of a UUID includes dashes. Sometimes that’s fine, sometimes it’s annoying.

import uuid

value = uuid.uuid4()
print(str(value))# with dashes
print(value.hex)# no dashes

.hex is handy for URLs, tokens, and compact storage.

Converting strings back to UUID objects

If you stored a UUID in a file or database as a string, you can recreate the UUID object like this:

import uuid

stored_id ="7c5f6c52-1f1d-4c8e-9a2a-4bfa9dfe2c9d"
real_uuid = uuid.UUID(stored_id)

print(real_uuid)
print(type(real_uuid))

That can be useful for validation, formatting, or comparisons.

If the input string is malformed, Python can raise a ValueError, and if you pass the wrong kind of object in some contexts, you may also hit a typeerror.

Comparing UUIDs

UUID objects compare nicely with each other.

import uuid

a = uuid.uuid4()
b = uuid.uuid4()

print(a == b)# almost always False

If you compare strings, make sure the formatting matches. A UUID string with dashes is different from its .hex version.

UUIDs vs random numbers

A random integer can work as an ID, but it’s easier to collide by accident, especially if you generate lots of values.

UUIDs are built for this exact job, and they are widely used across systems, databases, and APIs.

Their design helps reduce collisions, which is exactly why teams trust them for IDs generated on many machines at once.

When you might not want a UUID

UUIDs are great, but they’re not always the perfect choice.

• They’re longer than simple numeric IDs
• They don’t sort nicely by creation time (UUID4 is random)
• They can make some database indexes bigger

If you need sortable IDs, people sometimes use different approaches like ULIDs, time-based IDs, or database-generated IDs. Still, UUIDs remain one of the simplest and most reliable options in Python.

Looking inside a UUID object

A UUID object also exposes internal fields, which can help if you’re debugging or learning how the format works. For example, a UUID can be broken into parts like time_low, time_mid, time_hi_version, clock_seq_hi_variant, and clock_seq_low.

Version 1 UUIDs can also expose a node value tied to a hardware address. Python provides uuid.getnode() to fetch that machine-related number, though the exact value may vary depending on the device and environment.

When you access .fields, Python gives you a tuple containing those pieces in order, which is handy for inspection.

Name-based UUIDs also depend on input bytes. If you generate one from text, Python first encodes that text, commonly using utf-8. That detail usually stays behind the curtain, but it explains why the same text input gives the same UUID every time.

A version 1 UUID is sometimes called a time-based UUID. Both terms describe the same concept: a UUID built from time information plus node and clock sequence data.

Summary

The uuid module gives you a clean way to generate unique identifiers without relying on a database counter. Use uuid4() for random IDs, use .hex when you want compact strings, and use uuid5() when you need the same input to always produce the same ID.

Once you start generating IDs for users, uploads, and links, this module quickly becomes a favorite tool in your Python toolbox.