Definition

UUID v5 generates a deterministic UUID by hashing a namespace UUID and a name string using SHA-1. Given the same namespace and the same name, UUID v5 always produces the same UUID — on any machine, in any language, at any time. This makes it fundamentally different from UUID v4 and UUID v7, which generate a unique random or time-based value each time they are called.

The algorithm is defined in RFC 9562 §5.5.

How UUID v5 works

  1. Concatenate the 16-byte namespace UUID and the name string (as UTF-8 bytes)
  2. Compute SHA-1 of the concatenated bytes (produces 20 bytes)
  3. Take the first 16 bytes
  4. Set the version nibble (bits 48–51) to 0101 (5)
  5. Set the variant bits (bits 64–65) to 10 (RFC 9562 variant)

The result is a valid 128-bit UUID with version digit 5 at position 13 and a variant digit (8, 9, a, or b) at position 17.

Standard namespaces

RFC 9562 defines four standard namespace UUIDs:

NameUUIDUse for
DNS6ba7b810-9dad-11d1-80b4-00c04fd430c8Domain names
URL6ba7b811-9dad-11d1-80b4-00c04fd430c8URLs
OID6ba7b812-9dad-11d1-80b4-00c04fd430c8ISO OIDs
X.5006ba7b814-9dad-11d1-80b4-00c04fd430c8X.500 distinguished names

Using a standard namespace ensures your UUIDs are compatible with other systems generating v5 UUIDs for the same names. Using a custom namespace creates a private UUID space — IDs generated in your namespace cannot collide with IDs in another namespace even for the same name.

Code examples

JavaScript

import { v5 as uuidv5 } from 'uuid';

// Using built-in URL namespace
const id = uuidv5('https://example.com/resource/42', uuidv5.URL);
// Always: "0a300ee9-f9e4-5697-a51a-efc7fafaba67"

// Using a custom namespace (generate your own namespace UUID with v4 once)
const MY_NAMESPACE = 'b6c7d8e9-f0a1-4b2c-8d3e-9f0a1b2c3d4e';
const userId = uuidv5('user@example.com', MY_NAMESPACE);
// Always the same UUID for this email in this namespace

The uuid npm package provides v5() with all four standard namespace constants as properties on the function.

Python

import uuid

# Built-in NAMESPACE_URL constant
resource_id = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/resource/42')
# Always: UUID('0a300ee9-f9e4-5697-a51a-efc7fafaba67')

# DNS namespace — stable ID for a domain name
domain_id = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')

# Custom namespace
MY_NAMESPACE = uuid.UUID('b6c7d8e9-f0a1-4b2c-8d3e-9f0a1b2c3d4e')
user_id = uuid.uuid5(MY_NAMESPACE, 'user@example.com')

Python’s standard library uuid module has supported uuid5() since Python 2.5. The Python uuid module documentation covers all version generators and namespace constants.

Go

import "github.com/google/uuid"

// Using URL namespace
resourceId := uuid.NewSHA1(uuid.NameSpaceURL, []byte("https://example.com/resource/42"))
// Always: "0a300ee9-f9e4-5697-a51a-efc7fafaba67"

// Custom namespace
myNamespace := uuid.MustParse("b6c7d8e9-f0a1-4b2c-8d3e-9f0a1b2c3d4e")
userId := uuid.NewSHA1(myNamespace, []byte("user@example.com"))

The google/uuid package uses NewSHA1() for UUID v5 (SHA-1 based) and NewMD5() for UUID v3.

Use cases

Content-addressed identifiers

UUID v5 is the right choice when you need a stable ID for a resource defined by its content or canonical name:

// The UUID for a URL is always the same — use as a cache key
const pageUuid = uuidv5('https://myapp.com/products/widget', uuidv5.URL);

// Check cache without storing the UUID in a separate table
const cached = await redis.get(`page:${pageUuid}`);

Terraform deterministic IDs

Terraform’s built-in uuidv5() function uses UUID v5 for stable infrastructure IDs:

locals {
  env_id = uuidv5("dns", "${var.app_name}.${var.env}.internal")
  # Same UUID every plan/apply — no state required
}

Test fixtures

# Reproducible test UUIDs without storing state
NAMESPACE = uuid.UUID('test0000-0000-0000-0000-000000000001')

def test_user_id():
    user_id = uuid.uuid5(NAMESPACE, 'alice@example.com')
    assert str(user_id) == 'expected-stable-uuid-value'

UUID v5 vs UUID v7

PropertyUUID v5UUID v7
DeterministicYes — same inputs = same UUIDNo — random each call
Time-orderedNoYes
Requires inputYes — namespace + nameNo
Collision resistanceSHA-1 basedCSPRNG randomness
Use caseStable IDs from known dataPrimary keys, event IDs

UUID v5 and UUID v7 serve different purposes — they are not alternatives to each other. Use UUID v5 when you need to reproduce the same UUID from data; use UUID v7 when you need a new unique ID for each record.

External references

Frequently asked questions

What is UUID v5 used for?

UUID v5 generates a stable, deterministic UUID from any name within a given namespace — the same name in the same namespace always produces the same UUID, on any machine, at any time. Common use cases include generating stable IDs for content-addressed resources (the UUID of a URL is always the same UUID), creating reproducible test fixtures without storing state, and Terraform infrastructure IDs (via uuidv5()). The generation algorithm is defined in RFC 9562 §5.5.

What is the difference between UUID v3 and UUID v5?

UUID v3 uses MD5 to hash the namespace and name; UUID v5 uses SHA-1. Both produce deterministic UUIDs from the same inputs. UUID v5 is preferred over v3 because SHA-1 is cryptographically stronger than MD5 — though neither is collision-resistant by modern standards, SHA-1 is the recommended choice per RFC 9562 §6.5. For new systems use UUID v5; UUID v3 exists for backwards compatibility only.

How do I generate UUID v5 in JavaScript and Python?

In JavaScript, use the uuid npm package: import { v5 as uuidv5 } from 'uuid'; const id = uuidv5('https://example.com', uuidv5.URL);. The package includes built-in namespace constants uuidv5.DNS, uuidv5.URL, uuidv5.OID, and uuidv5.X500. In Python, use the standard library: import uuid; id = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com'). Both produce the same UUID for the same inputs — interoperable across languages.