[Python] UUID Generation and Types (v1, v4, v3, v5): Namespaces and Uniqueness

2025年12月20日

A UUID (Universally Unique Identifier) is an identifier used to generate globally unique IDs without central management. It is represented as a 128-bit number in hexadecimal format, looking like 550e8400-e29b-41d4-a716-446655440000.

Using Python’s standard uuid library, you can easily generate four different types of UUIDs depending on your needs.

List of Namespace Constants

When using UUID versions 3 and 5 (name-based), you must specify a “Namespace” constant.

Constant Name	Meaning / Usage
`uuid.NAMESPACE_DNS`	When specifying a FQDN (Fully Qualified Domain Name)
`uuid.NAMESPACE_URL`	When specifying a URL
`uuid.NAMESPACE_OID`	When specifying an ISO OID (Object Identifier)
`uuid.NAMESPACE_X500`	When specifying an X.500 DN (Distinguished Name)

Implementation Example 1: Random (v4) and Time-Based (v1)

Generally, the completely random v4 is the most commonly used.

v1 includes the MAC address, so while it allows identifying the source, you must be careful regarding privacy.

Source Code

import uuid

# --- 1. UUID v4 (Random based) ---
# Generated using random numbers. The collision probability is astronomically low,
# so it is recommended for general-purpose IDs.
# Examples: Session IDs for Web apps, Primary Keys for DBs, etc.
random_id = uuid.uuid4()

print("--- UUID v4 (Random) ---")
print(f"ID  : {random_id}")
print(f"Type: {type(random_id)}")
print(f"Hex : {random_id.hex}") # String without hyphens

# --- 2. UUID v1 (Time + MAC address based) ---
# Generated using the current time and the machine's MAC address.
# Used when you want to maintain generation order to some extent or identify nodes.
time_based_id = uuid.uuid1()

print("\n--- UUID v1 (Time + MAC) ---")
print(f"ID  : {time_based_id}")

Execution Result

--- UUID v4 (Random) ---
ID  : a2c4e6b8-9012-4def-abcd-1234567890ab
Type: <class 'uuid.UUID'>
Hex : a2c4e6b890124defabcd1234567890ab

--- UUID v1 (Time + MAC) ---
ID  : 123e4567-e89b-12d3-a456-426614174000

Implementation Example 2: Generating from Specific Names (v3, v5)

If you want to generate the same UUID consistently based on a specific string (such as a domain name or user ID), use v3 (MD5) or v5 (SHA-1), which utilize hash functions.

From a security perspective, using v5 is currently recommended.

Source Code

import uuid

# The source string for ID generation (Scenario: Creating an identifier for an internal API)
target_domain = "api.internal-system.local"

# --- 1. UUID v3 (MD5 hash) ---
# Generate by passing a namespace (DNS) and a string
generated_uuid_v3 = uuid.uuid3(uuid.NAMESPACE_DNS, target_domain)

# --- 2. UUID v5 (SHA-1 hash) ---
# Uses SHA-1, which has higher collision resistance than v3. This is recommended.
generated_uuid_v5 = uuid.uuid5(uuid.NAMESPACE_DNS, target_domain)

print(f"Target Domain: {target_domain}")
print("-" * 40)
print(f"v3 (MD5)  : {generated_uuid_v3}")
print(f"v5 (SHA-1): {generated_uuid_v5}")

# Verification: The same input produces the same UUID every time
re_generated = uuid.uuid5(uuid.NAMESPACE_DNS, target_domain)
print(f"Re-generation check : {re_generated} (Match: {generated_uuid_v5 == re_generated})")

Execution Result

Target Domain: api.internal-system.local
----------------------------------------
v3 (MD5)  : 6fa459ea-ee8a-3ca4-894e-db77e160355e
v5 (SHA-1): 886313e1-3b8a-5372-9b90-0c9aee199e5d
Re-generation check : 886313e1-3b8a-5372-9b90-0c9aee199e5d (Match: True)

Explanation

Choosing the Version

uuid4 (Recommended): When you simply want a unique ID. This is the most common choice.
uuid5: When you want to always assign a “fixed ID B” to “Input Data A” (when consistency is required).
uuid1: When you need generation timestamp information or want to identify the physical machine using the MAC address (Note: Be mindful of privacy).