UUID Namespaces — Deterministic UUIDs with v3 and v5

UUID v3 and v5 are “name-based” UUIDs — given the same namespace UUID and the same name string, they always produce the same output UUID. This makes them useful for content addressing, deduplication, and any scenario where the same logical entity should map to the same identifier across systems.

How Name-Based UUIDs Work

The algorithm:

1. Concatenate the namespace UUID’s 16 bytes with the name string’s UTF-8 bytes
2. Hash the result: MD5 for v3, SHA-1 for v5
3. Take the first 16 bytes of the hash
4. Set the version nibble (position 76–79) to 0011 (v3) or 0101 (v5)
5. Set the variant bits (position 64–65) to 10

Because the hash function is deterministic, the same inputs always produce the same UUID. This is fundamentally different from v4 and v7, which use random bits.

Predefined Namespaces

RFC 9562 §6.6 defines four predefined namespaces:

You can also define your own namespace by generating a UUID v4 once and using it as the namespace for your application or domain.

Generating UUID v5 in Practice

JavaScript — uuid npm package:

import { v5 as uuidv5 } from 'uuid';

const DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const id = uuidv5('example.com', DNS);
// Always: "cfbff0d1-9375-5685-968c-48ce8b15ae17"

Python — standard library:

import uuid

DNS = uuid.NAMESPACE_DNS
id = uuid.uuid5(DNS, 'example.com')
# Always: UUID('cfbff0d1-9375-5685-968c-48ce8b15ae17')

Go — google/uuid:

import "github.com/google/uuid"

dns := uuid.NameSpaceDNS
id := uuid.NewSHA1(dns, []byte("example.com"))
// Always: cfbff0d1-9375-5685-968c-48ce8b15ae17

When to Use Namespace UUIDs

Content addressing: Hash a file’s content or URL to produce a stable UUID. The same content always maps to the same UUID, enabling deduplication in object stores or event logs.

Idempotent record creation: When importing records from an external system, use the source system’s string ID as the name and a fixed namespace to produce a deterministic UUID. Re-importing the same record produces the same UUID — no duplicate checks needed.

Synthetic test data: Generate consistent UUIDs in tests by seeding from a known name. Tests are reproducible without storing expected UUIDs in fixtures.

Federated identity: Two systems that agree on a namespace and naming convention can independently generate the same UUID for the same logical entity without coordination.

What Namespace UUIDs Are Not For

• Security tokens — name-based UUIDs are deterministic and therefore predictable if the name is known. Do not use them as secrets.
• Primary keys for user-generated content — if two users submit the same content, they would receive the same UUID. Use v4 or v7 for records that must be distinct regardless of content.
• High-throughput inserts — SHA-1 hashing adds CPU overhead compared to v4/v7 generation. For bulk inserts, v7 is faster.

Custom Namespaces

To define your own namespace, generate a UUID v4 once and document it as your application’s namespace constant:

// Your application's permanent namespace
const MY_APP_NS = '7c9e6679-7425-40de-944b-e07fc1f90ae7'; // generated once, fixed forever

const userId = uuidv5(`user:${email}`, MY_APP_NS);

Store this namespace constant in your codebase — it must never change. Different values produce different UUIDs for the same name.

Related Resources

• RFC 9562 §6.6 — predefined namespace UUIDs
• uuid npm package — v5 implementation
• Python uuid.uuid5() documentation
• google/uuid NewSHA1 documentation