:mod:`!uuid` --- UUID objects according to RFC 9562
.. module:: uuid :synopsis: UUID objects (universally unique identifiers) according to RFC 9562
.. moduleauthor:: Ka-Ping Yee <[email protected]>
.. sectionauthor:: George Yoshida <[email protected]>
Source code: :source:`Lib/uuid.py`
This module provides immutable :class:`UUID` objects (the :class:`UUID` class) and :ref:`functions <uuid-factory-functions>` for generating UUIDs corresponding to a specific UUID version as specified in RFC 9562 (which supersedes RFC 4122), for example, :func:`uuid1` for UUID version 1, :func:`uuid3` for UUID version 3, and so on. Note that UUID version 2 is deliberately omitted as it is outside the scope of the RFC.
If all you want is a unique ID, you should probably call :func:`uuid1` or :func:`uuid4`. Note that :func:`uuid1` may compromise privacy since it creates a UUID containing the computer's network address. :func:`uuid4` creates a random UUID.
Depending on support from the underlying platform, :func:`uuid1` may or may not return a "safe" UUID. A safe UUID is one which is generated using synchronization methods that ensure no two processes can obtain the same UUID. All instances of :class:`UUID` have an :attr:`~UUID.is_safe` attribute which relays any information about the UUID's safety, using this enumeration:
.. versionadded:: 3.7
.. attribute:: SafeUUID.safe The UUID was generated by the platform in a multiprocessing-safe way.
.. attribute:: SafeUUID.unsafe The UUID was not generated in a multiprocessing-safe way.
.. attribute:: SafeUUID.unknown The platform does not provide information on whether the UUID was generated safely or not.
:class:`UUID` instances have these read-only attributes:
.. attribute:: UUID.bytes The UUID as a 16-byte string (containing the six integer fields in big-endian byte order).
.. attribute:: UUID.bytes_le The UUID as a 16-byte string (with *time_low*, *time_mid*, and *time_hi_version* in little-endian byte order).
.. attribute:: UUID.fields A tuple of the six integer fields of the UUID, which are also available as six individual attributes and two derived attributes:
| Field | Meaning |
.. attribute:: UUID.time_low |
The first 32 bits of the UUID. Only relevant to version 1. |
.. attribute:: UUID.time_mid |
The next 16 bits of the UUID. Only relevant to version 1. |
.. attribute:: UUID.time_hi_version |
The next 16 bits of the UUID. Only relevant to version 1. |
.. attribute:: UUID.clock_seq_hi_variant |
The next 8 bits of the UUID. Only relevant to versions 1 and 6. |
.. attribute:: UUID.clock_seq_low |
The next 8 bits of the UUID. Only relevant to versions 1 and 6. |
.. attribute:: UUID.node |
The last 48 bits of the UUID. Only relevant to version 1. |
.. attribute:: UUID.time |
The 60-bit timestamp as a count of 100-nanosecond intervals since Gregorian epoch (1582-10-15 00:00:00) for versions 1 and 6, or the 48-bit timestamp in milliseconds since Unix epoch (1970-01-01 00:00:00) for version 7. |
.. attribute:: UUID.clock_seq |
The 14-bit sequence number. Only relevant to versions 1 and 6. |
.. attribute:: UUID.hex The UUID as a 32-character lowercase hexadecimal string.
.. attribute:: UUID.int The UUID as a 128-bit integer.
.. attribute:: UUID.urn The UUID as a URN as specified in :rfc:`9562`.
.. attribute:: UUID.variant The UUID variant, which determines the internal layout of the UUID. This will be one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`, :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`.
.. attribute:: UUID.version
The UUID version number (1 through 8, meaningful only when the variant is
:const:`RFC_4122`).
.. versionchanged:: 3.14
Added UUID versions 6, 7 and 8.
.. attribute:: UUID.is_safe An enumeration of :class:`SafeUUID` which indicates whether the platform generated the UUID in a multiprocessing-safe way. .. versionadded:: 3.7
The :mod:`uuid` module defines the following functions:
.. function:: getnode()
Get the hardware address as a 48-bit positive integer. The first time this
runs, it may launch a separate program, which could be quite slow. If all
attempts to obtain the hardware address fail, we choose a random 48-bit
number with the multicast bit (least significant bit of the first octet)
set to 1 as recommended in :rfc:`4122`. "Hardware address" means the MAC
address of a network interface. On a machine with multiple network
interfaces, universally administered MAC addresses (i.e. where the second
least significant bit of the first octet is *unset*) will be preferred over
locally administered MAC addresses, but with no other ordering guarantees.
.. versionchanged:: 3.7
Universally administered MAC addresses are preferred over locally
administered MAC addresses, since the former are guaranteed to be
globally unique, while the latter are not.
.. function:: uuid1(node=None, clock_seq=None) Generate a UUID from a host ID, sequence number, and the current time. If *node* is not given, :func:`getnode` is used to obtain the hardware address. If *clock_seq* is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.
.. function:: uuid3(namespace, name) Generate a UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a :class:`bytes` object or a string that will be encoded using UTF-8).
.. function:: uuid4() Generate a random UUID.
.. function:: uuid5(namespace, name) Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a :class:`bytes` object or a string that will be encoded using UTF-8).
.. function:: uuid6(node=None, clock_seq=None) Generate a UUID from a sequence number and the current time according to :rfc:`9562`. This is an alternative to :func:`uuid1` to improve database locality. When *node* is not specified, :func:`getnode` is used to obtain the hardware address as a 48-bit positive integer. When a sequence number *clock_seq* is not specified, a pseudo-random 14-bit positive integer is generated. If *node* or *clock_seq* exceed their expected bit count, only their least significant bits are kept. .. versionadded:: 3.14
.. function:: uuid7() Generate a time-based UUID according to :rfc:`RFC 9562, §5.7 <9562#section-5.7>`. For portability across platforms lacking sub-millisecond precision, UUIDs produced by this function embed a 48-bit timestamp and use a 42-bit counter to guarantee monotonicity within a millisecond. .. versionadded:: 3.14
.. function:: uuid8(a=None, b=None, c=None) Generate a pseudo-random UUID according to :rfc:`RFC 9562, §5.8 <9562#section-5.8>`. When specified, the parameters *a*, *b* and *c* are expected to be positive integers of 48, 12 and 62 bits respectively. If they exceed their expected bit count, only their least significant bits are kept; non-specified arguments are substituted for a pseudo-random integer of appropriate size. .. versionadded:: 3.14
The :mod:`uuid` module defines the following namespace identifiers for use with :func:`uuid3` or :func:`uuid5`.
.. data:: NAMESPACE_DNS When this namespace is specified, the *name* string is a fully qualified domain name.
.. data:: NAMESPACE_URL When this namespace is specified, the *name* string is a URL.
.. data:: NAMESPACE_OID When this namespace is specified, the *name* string is an ISO OID.
.. data:: NAMESPACE_X500 When this namespace is specified, the *name* string is an X.500 DN in DER or a text output format.
The :mod:`uuid` module defines the following constants for the possible values of the :attr:`~UUID.variant` attribute:
.. data:: RESERVED_NCS Reserved for NCS compatibility.
.. data:: RFC_4122 Specifies the UUID layout given in :rfc:`4122`. This constant is kept for backward compatibility even though :rfc:`4122` has been superseded by :rfc:`9562`.
.. data:: RESERVED_MICROSOFT Reserved for Microsoft compatibility.
.. data:: RESERVED_FUTURE Reserved for future definition.
The :mod:`uuid` module defines the special Nil and Max UUID values:
.. data:: NIL A special form of UUID that is specified to have all 128 bits set to zero according to :rfc:`RFC 9562, §5.9 <9562#section-5.9>`. .. versionadded:: 3.14
.. data:: MAX A special form of UUID that is specified to have all 128 bits set to one according to :rfc:`RFC 9562, §5.10 <9562#section-5.10>`. .. versionadded:: 3.14
.. seealso::
:rfc:`9562` - A Universally Unique IDentifier (UUID) URN Namespace
This specification defines a Uniform Resource Name namespace for UUIDs, the
internal format of UUIDs, and methods of generating UUIDs.
.. versionadded:: 3.12
The :mod:`uuid` module can be executed as a script from the command line.
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]The following options are accepted:
.. program:: uuid
.. option:: -h, --help Show the help message and exit.
.. option:: -u <uuid>
--uuid <uuid>
Specify the function name to use to generate the uuid. By default :func:`uuid4`
is used.
.. versionchanged:: 3.14
Allow generating UUID versions 6, 7 and 8.
.. option:: -n <namespace>
--namespace <namespace>
The namespace is a ``UUID``, or ``@ns`` where ``ns`` is a well-known predefined UUID
addressed by namespace name. Such as ``@dns``, ``@url``, ``@oid``, and ``@x500``.
Only required for :func:`uuid3` / :func:`uuid5` functions.
.. option:: -N <name>
--name <name>
The name used as part of generating the uuid. Only required for
:func:`uuid3` / :func:`uuid5` functions.
.. option:: -C <num>
--count <num>
Generate *num* fresh UUIDs.
.. versionadded:: 3.14
Here are some examples of typical usage of the :mod:`uuid` module:
>>> import uuid
>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'
>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')
>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
>>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
>>> u = uuid.uuid7()
>>> u.time # doctest: +SKIP
1743936859822
>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000) # doctest: +SKIP
datetime.datetime(...)
Here are some examples of typical usage of the :mod:`uuid` command-line interface:
# generate a random UUID - by default uuid4() is used
$ python -m uuid
# generate a UUID using uuid1()
$ python -m uuid -u uuid1
# generate a UUID using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com
# generate 42 random UUIDs
$ python -m uuid -C 42