uuid – Universally unique identifiers

Purpose:The uuid module implements Universally Unique Identifiers as described in RFC 4122.
Available In:2.5 and later

RFC 4122 defines a system for creating universally unique identifiers for resources in a way that does not require a central registrar. UUID values are 128 bits long and “can guarantee uniqueness across space and time”. They are useful for identifiers for documents, hosts, application clients, and other situations where a unique value is necessary. The RFC is specifically geared toward creating a Uniform Resource Name namespace.

Three main algorithms are covered by the spec:

  • Using IEEE 802 MAC addresses as a source of uniqueness
  • Using pseudo-random numbers
  • Using well-known strings combined with cryptographic hashing

In all cases the seed value is combined with the system clock and a clock sequence value (to maintain uniqueness in case the clock was set backwards).

UUID 1 - IEEE 802 MAC Address

UUID version 1 values are computed using the MAC address of the host. The uuid module uses getnode() to retrieve the MAC value on a given system:

import uuid

print hex(uuid.getnode())
$ python uuid_getnode.py


If a system has more than one network card, and so more than one MAC, any one of the values may be returned.

To generate a UUID for a given host, identified by its MAC address, use the uuid1() function. You can pass a node identifier, or leave the field blank to use the value returned by getnode().

import uuid

u = uuid.uuid1()

print u
print type(u)
print 'bytes   :', repr(u.bytes)
print 'hex     :', u.hex
print 'int     :', u.int
print 'urn     :', u.urn
print 'variant :', u.variant
print 'version :', u.version
print 'fields  :', u.fields
print '\ttime_low            : ', u.time_low
print '\ttime_mid            : ', u.time_mid
print '\ttime_hi_version     : ', u.time_hi_version
print '\tclock_seq_hi_variant: ', u.clock_seq_hi_variant
print '\tclock_seq_low       : ', u.clock_seq_low
print '\tnode                : ', u.node
print '\ttime                : ', u.time
print '\tclock_seq           : ', u.clock_seq

The components of the UUID object returned can be accessed through read-only instance attributes. Some attributes, such as hex, int, and urn, are different representations of the UUID value.

$ python uuid_uuid1.py

<class 'uuid.UUID'>
bytes   : '%\x00\xb3.|\x1b\x11\xe2\x83\np\xcd`\xf2\xc9\x80'
hex     : 2500b32e7c1b11e2830a70cd60f2c980
int     : 49185070078265283276219513639424674176
urn     : urn:uuid:2500b32e-7c1b-11e2-830a-70cd60f2c980
variant : specified in RFC 4122
version : 1
fields  : (620802862L, 31771L, 4578L, 131L, 10L, 124027397130624L)
        time_low            :  620802862
        time_mid            :  31771
        time_hi_version     :  4578
        clock_seq_hi_variant:  131
        clock_seq_low       :  10
        node                :  124027397130624
        time                :  135807394801300270
        clock_seq           :  778

Because of the time component, each time uuid1() is called a new value is returned.

import uuid

for i in xrange(3):
    print uuid.uuid1()

Notice in this output that only the time component (at the beginning of the string) changes.

$ python uuid_uuid1_repeat.py


Because your computer has a different MAC address than mine, you will see entirely different values if you run the examples, because the node identifier at the end of the UUID will change, too.

import uuid

node1 = uuid.getnode()
print hex(node1), uuid.uuid1(node1)

node2 =  0x1e5274040e
print hex(node2), uuid.uuid1(node2)
$ python uuid_uuid1_othermac.py

0x70cd60f2c980 250ff58c-7c1b-11e2-9808-70cd60f2c980
0x1e5274040e 25106559-7c1b-11e2-9e48-001e5274040e

UUID 3 and 5 - Name-Based Values

It is also useful in some contexts to create UUID values from names instead of random or time-based values. Versions 3 and 5 of the UUID specification use cryptographic hash values (MD5 or SHA-1) to combine namespace-specific seed values with “names” (DNS hostnames, URLs, object ids, etc.). There are several well-known namespaces, identified by pre-defined UUID values, for working with DNS, URLs, ISO OIDs, and X.500 Distinguished Names. You can also define your own application- specific namespaces by generating and saving UUID values.

To create a UUID from a DNS name, pass uuid.NAMESPACE_DNS as the namespace argument to uuid3() or uuid5():

import uuid

hostnames = ['www.doughellmann.com', 'blog.doughellmann.com']

for name in hostnames:
    print name
    print '\tMD5   :', uuid.uuid3(uuid.NAMESPACE_DNS, name)
    print '\tSHA-1 :', uuid.uuid5(uuid.NAMESPACE_DNS, name)
$ python uuid_uuid3_uuid5.py

        MD5   : bcd02e22-68f0-3046-a512-327cca9def8f
        SHA-1 : e3329b12-30b7-57c4-8117-c2cd34a87ce9
        MD5   : 9bdabfce-dfd6-37ab-8a3f-7f7293bcf111
        SHA-1 : fa829736-7ef8-5239-9906-b4775a5abacb

The UUID value for a given name in a namespace is always the same, no matter when or where it is calculated. Values for the same name in different namespaces are different.

import uuid

for i in xrange(3):
    print uuid.uuid3(uuid.NAMESPACE_DNS, 'www.doughellmann.com')
$ python uuid_uuid3_repeat.py


UUID 4 - Random Values

Sometimes host-based and namespace-based UUID values are not “different enough”. For example, in cases where you want to use the UUID as a lookup key, a more random sequence of values with more differentiation is desirable to avoid collisions in a hash table. Having values with fewer common digits also makes it easier to find them in log files. To add greater differentiation in your UUIDs, use uuid4() to generate them using random input values.

import uuid

for i in xrange(3):
    print uuid.uuid4()
$ python uuid_uuid4.py


Working with UUID Objects

In addition to generating new UUID values, you can parse strings in various formats to create UUID objects. This makes it easier to compare them, sort them, etc.

import uuid

def show(msg, l):
    print msg
    for v in l:
        print '\t', v

input_values = [ 

show('input_values', input_values)

uuids = [ uuid.UUID(s) for s in input_values ]
show('converted to uuids', uuids)

show('sorted', uuids)
$ python uuid_uuid_objects.py


converted to uuids


See also

Standard library documentation for this module.
RFC 4122
A Universally Unique IDentifier (UUID) URN Namespace