uuid.uuid1

The timestamp counts 100-nanosecond steps since 1582-10-15; node defaults to getnode(), the hardware address; clock_seq defaults to 14 random bits. The docs warn that uuid1 "may compromise privacy" because of that address.

uuid functionPython 2.5+Live demo
Common call
uuid.uuid1()
Returns
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') (time-based)
Replaces
Hand-built time + host IDs
Watch out
The last group is your MAC address unless you pass node=
uuid.uuid1(nodenode — The 48-bit node; None means getnode(). On 3.13 a value of 2**48 or more raises ValueError.type: int | None · default: None=None, clock_seqclock_seq — The sequence number; only its low 14 bits are used. None means random.getrandbits(14).type: int | None · default: None=None)
→ uuid.UUID

Demo

Live evaluation
With node and clock_seq given, everything but the timestamp is fixed. These are the parts that do not change between runs.
Try:
Inputs
nodeintbelow 2**48 = 281474976710656
seqintclock sequence
Code
import uuid
u = uuid.uuid1(node=20015998343868, clock_seq=4660)
(hex(u.node), u.clock_seq, u.version, u.variant)
Result
('0x123456789abc', 4660, 1, 'specified in RFC 4122')

clock_seq is masked to 14 bits: 20000 becomes 3616 and -1 becomes 16383 (Python's & works on negative ints as if they had infinitely many 1 bits). node is not masked on 3.13: 2**48 fails the 48-bit check of UUID(fields=...). The timestamp is not shown because it changes with every call.

Parameters

NameTypeRequiredDescription
nodeint | Noneno (None)The 48-bit node; None means getnode(). On 3.13 a value of 2**48 or more raises ValueError.
clock_seqint | Noneno (None)The sequence number; only its low 14 bits are used. None means random.getrandbits(14).

Return value

uuid.UUID — A version 1 UUID: 60-bit timestamp, 14-bit clock sequence, 48-bit node.

Common patterns

uuid1 without the MAC address
Pass a random 48-bit node with the multicast bit set, as RFC 4122 recommends when no real address is used.
import random, uuid
node = random.getrandbits(48) | (1 << 40)
u = uuid.uuid1(node=node)
When was it made?
Decode the timestamp (UTC) from a version 1 UUID.
import uuid
from datetime import datetime, timedelta
made = datetime(1582, 10, 15) + timedelta(microseconds=u.time // 10)

Examples

1. Version 1, RFC 4122 variant
import uuid u = uuid.uuid1() (u.version, u.variant)
Returns
(1, 'specified in RFC 4122')
2. node and clock_seq end up in the fields
import uuid u = uuid.uuid1(node=0x123456789abc, clock_seq=0x1234) (hex(u.node), hex(u.clock_seq))
Returns
('0x123456789abc', '0x1234')
3. The last group is the node
import uuid str(uuid.uuid1(node=0x123456789abc))[-12:]
Returns
'123456789abc'
4. Default node is getnode()
import uuid uuid.uuid1().node == uuid.getnode()
Returns
True
5. Later calls sort later
import uuid a = uuid.uuid1() b = uuid.uuid1() b.time > a.time
Returns
True
6. Node too large
import uuid uuid.uuid1(node=1 << 48)
Returns
ValueError: field 6 out of range (need a 48-bit value)

Pitfalls

1. Publishing uuid1 values
Anyone can read the machine address and the creation time back out of a uuid1. For public IDs use uuid4.
uuid1 leaks
import uuid
uuid.uuid1().node == uuid.getnode()
True
uuid4
import uuid
uuid.uuid4().version
4
2. Sorting uuid1 values as UUIDs
UUIDs sort by their int, which starts with time_low: the LOW 32 bits of the timestamp. Sort by u.time instead.
sort by UUID
import uuid
early = uuid.UUID(fields=(0xffffffff, 0, 0x1000, 0x80, 0, 1))
late = uuid.UUID(fields=(0, 1, 0x1000, 0x80, 0, 1))
sorted([late, early])[0] == early
False
sort by u.time
import uuid
early = uuid.UUID(fields=(0xffffffff, 0, 0x1000, 0x80, 0, 1))
late = uuid.UUID(fields=(0, 1, 0x1000, 0x80, 0, 1))
sorted([late, early], key=lambda u: u.time)[0] == early
True

When to use

Use it
  • Legacy systems that expect version 1 UUIDs
  • Internal IDs where the embedded time is useful and the address is not a concern
Reach for something else
  • Public or user-facing IDs → uuid4 (no address, no time)
  • Database keys that must sort by time → u.time is not the sort order of UUIDs; 3.14 adds uuid6/uuid7 for that

Notes

CPython impl
Lib/uuid.py: if the platform provides uuid_generate_time_safe (via the _uuid extension) and neither argument is given, that is used; otherwise time.time_ns() // 100 + 0x01b21dd213814000, bumped by 1 if not later than the previous call, and UUID(fields=..., version=1)
is_safe
Only uuid1 can set is_safe to safe/unsafe, when the platform generator reports it. On Windows CPython 3.13 and on Ubuntu (WSL) CPython 3.12, uuid._generate_time_safe was None and is_safe was SafeUUID.unknown
3.14
The 3.14 docs say that node or clock_seq values wider than their bit count keep only their least significant bits; 3.13 masks clock_seq but raises ValueError for node

FAQ

Yes, by default: node is getnode(), the hardware address of a network interface (or a random number with the multicast bit set if none is found). Pass node= to avoid it, or use uuid4.