UUID Validation in Python — Versions, Variants, and Common Pitfalls

1. Why UUID validation matters

A Universally Unique Identifier (UUID) is a 128-bit label used to identify resources across systems without coordination. UUIDs appear as database primary keys (PostgreSQL's uuid type), distributed system node identifiers, message deduplication keys, and API idempotency tokens.

Accepting an invalid UUID can corrupt your data layer, cause silent lookup failures, or break downstream services that expect a specific version. In event-driven architectures, a malformed idempotency key can lead to duplicate processing or lost events.

2. UUID versions explained

Not all UUIDs are random. Each version encodes different information and is suited for different use cases:

3. The anatomy of a UUID

A UUID is displayed as 32 hexadecimal digits in the canonical 8-4-4-4-12 format, separated by hyphens:

4. Why regex isn't enough

The most common approach to UUID validation in Python is a regex like this:

import re

# ❌ Matches the format but ignores version and variant
UUID_REGEX = re.compile(
    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
    re.IGNORECASE,
)

Python's standard library also provides uuid.UUID(), which parses UUIDs but does not validate version or variant semantics:

import uuid

# ⚠️ Parses successfully but doesn't reject invalid versions
parsed = uuid.UUID("550e8400-e29b-f1d4-a716-446655440000")  # version nibble = f
print(parsed.version)  # Raises ValueError for non-standard versions in some Python builds

Both approaches miss critical semantic checks:

5. The right solution — IsValid API

The IsValid UUID API validates the format, detects the version (0-15) and variant (RFC 4122, NCS, Microsoft, or future), and optionally enforces a specific version — all in a single call.

Pass any string to the API and get back whether it is a valid UUID, which version it is, and which variant it uses. You can also filter by a specific version to reject UUIDs that don't match your requirements.

Full parameter reference and response schema: UUID API docs →

6. Python code example

Using the isvalid-sdk Python SDK or the popular requests library. Install either with pip install isvalid-sdk or pip install requests.

# validate_uuid.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── Basic validation ─────────────────────────────────────────────────────────

result = iv.uuid("550e8400-e29b-41d4-a716-446655440000")

print(result["valid"])    # True
print(result["version"])  # 4
print(result["variant"])  # 'rfc4122'

# ── Enforce a specific version ───────────────────────────────────────────────

v7 = iv.uuid("01932c07-209c-7f43-b572-6a8270527ca5", version=7)

if not v7["valid"]:
    print("Not a valid v7 UUID")

# dependencies.py (FastAPI)
from fastapi import Depends, HTTPException, Path


async def validated_uuid(
    resource_id: str = Path(..., description="Resource UUID"),
) -> str:
    """Validate that the path parameter is a valid v4 UUID."""
    result = iv.uuid(resource_id, version=4)
    if not result["valid"]:
        raise HTTPException(
            status_code=400,
            detail="Invalid resource ID — expected a valid v4 UUID",
        )
    return resource_id


# Usage in a route:
# @app.get("/resources/{resource_id}")
# async def get_resource(resource_id: str = Depends(validated_uuid)):
#     ...

7. cURL example

Validate a UUID from the command line:

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "value=550e8400-e29b-41d4-a716-446655440000" \
  "https://api.isvalid.dev/v0/uuid"

Enforce a specific version (returns valid: false if the UUID is not v7):

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "value=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "version=7" \
  "https://api.isvalid.dev/v0/uuid"

8. Understanding the response

Valid v4 UUID:

{
  "valid": true,
  "version": 4,
  "variant": "rfc4122"
}

Invalid UUID (wrong format):

{
  "valid": false,
  "version": null,
  "variant": null
}

9. Edge cases

nil_result = iv.uuid("00000000-0000-0000-0000-000000000000")
# {"valid": True, "version": 0, "variant": "ncs"}