---
name: "uuid"
section: "1"
platform: "linux"
package: "uuid"
version: "1.6.4-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/uuid"
---

# uuid(1)

generate, convert, and decode Universally Unique IDentifiers

## NAME

**uuid** – generate, convert, and decode Universally Unique IDentifiers

## SYNOPSIS

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] \[**-v** **1**\] \[**-m1**\]

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-v** **3** *uuid*\|**nil**\|**max**\|**ns:**{**DNS**\|**URL**\|**OID**\|**X500**} *data*

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-v** **4**

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-v** **5** *uuid*\|**nil**\|**max**\|**ns:**{**DNS**\|**URL**\|**OID**\|**X500**} *data*

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-v** **6**

**uuid** \[**-n** *count*\] \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-v** **7**

**uuid** **-d** \[**-o** *outfile*\] \[ **-F**  **STR**\|**SIV**\] *uuid*

**uuid** **-d** \[**-o** *outfile*\] \[**-r**\|**-F** **BIN**\|**STR**\|**SIV**\] **-**

## DESCRIPTION

By default, generates a UUID (Universally Unique Identifier), of a version specified by **-v** (default **1**) in the canonical **STR**ing format.\
 With **-d**, decodes *uuid* (or reads it in from the standard input stream if "**-**"), yielding something akin to

```
encode: STR:     92a3d3de-6bbf-11ef-9f5b-774ebb537938
        SIV:     194917928982963228599463962120788605240
decode: variant: DCE 1.1, ISO/IEC 11578:1996
        version: 1 (time and node based)
        content: time:  2024-09-05 19:46:41.491043.0 UTC
                 clock: 8027 (usually random)
                 node:  77:4e:bb:53:79:38 (local multicast)
```

or

```
encode: STR:     7e017d98-cecc-41f6-8030-552d23cd38e6
        SIV:     167490467173639937831846401373276813542
decode: variant: DCE 1.1, ISO/IEC 11578:1996
        version: 4 (random data based)
        content: 7E:01:7D:98:CE:CC:01:F6:00:30:55:2D:23:CD:38:E6
                 (no semantics: random data only)
```

A UUID is a 128-bit (16-byte) number whose format (method of generation) makes it very likely that it will be unique, both spatially and temporally. This makes them well-suited for identifying anything from ephemera like database queries to databases themselves.

The three principal **-F**ormats are:

- **STR**ing

  01234567-890a-bcde-f012-3456789abcde (hexadecimal string broken up by dashes)

- **SIV** (Single Integer Value)

  128-bit decimal integer

- **BIN**ary or "raw"

  the 16 bytes of the UUID in big endian order (most significant first)

UUIDs come in a few **-v**ersions:

- **1**

  based on the current time (to the precision of 100ns), and the host's MAC address (this implementation uses the MAC address of the first NIC it finds, unless **-m**, in which case random data is substituted for the MAC)

- **6**

  very similar, but the most significant (slowest-changing) parts of the timestamp are stored first, which improves locality in some database applications

- **7**

  contains the current *UNIX* time — versions **1** and **6** encode a UUID time which is off by like 400 years — (to the precision of 1ms), then 10 bytes of random data.\
   *This* *version* *should* *be* *preferred* *to* *1* *and* *6.*

- **3**

  hashes the "namespace" (first argument, either a **STR**ing-format UUID or a well-known name (see below)) and the "name" (second argument, arbitrary data) with the MD5(3) digest, and uses that directly (a few branding bytes are replaced to identify the format)

- **5**

  the same as version **3**, but uses the first 16 bytes of the SHA1(3) digest

- **4**

  just random data

The namespaces understood when generating version 3 and 5 UUIDs are:

- *uuid*

  (any valid **STR**ingified UUID)

- **nil**

  00000000-0000-0000-0000-000000000000 — the special all-zero UUID

- **max**

  ffffffff-ffff-ffff-ffff-ffffffffffff — the special all-bits-set/sorts-after-everything sentinel UUID

- **ns:DNS**

  6ba7b810-9dad-11d1-80b4-00c04fd430c8 — for fully-qualified domain names

- **ns:URL**

  6ba7b811-9dad-11d1-80b4-00c04fd430c8 — for URLs

- **ns:OID**

  6ba7b812-9dad-11d1-80b4-00c04fd430c8 — for ISO OIDs

- **ns:X500**

  6ba7b814-9dad-11d1-80b4-00c04fd430c8 — for X.500 Distinguished Names

## OPTIONS

- **-n** *count*

  Generate *count* UUIDs. Defaults to **1**.

- **-o** *outfile*

  Write to *outfile*.

- **-F** **BIN**\|**STR**\|**SIV**

  Produce output in the given format. Defaults to **STR**.

- **-r**

  **-F** **BIN**

- **-v** **1**\|**3**\|**4**\|**5**\|**6**\|**7**

  Version to generate. Defaults to **1**.

- **-m**

  **-v** **1**\|**6** only: ignore the current host's MAC addresses, use random data instead (this may still happen if the if a MAC can't be determined or all MACs are multicast).

- **-1**

  **-v** **1** only, *count* \>1 only: generate each UUID independently. Version 1 UUIDs have a field that increases monotonically within a session; thus, for example, in

  ```
  $ uuid -n 4
  366ab5a3-6bc4-11ef-a31a-0026b986fdd4
  366ab5ce-6bc4-11ef-a31b-0026b986fdd4
  366ab5f8-6bc4-11ef-a31c-0026b986fdd4
  366ab621-6bc4-11ef-a31d-0026b986fdd4
                     ^^^^
  ```

  the highlighted column *starts* random, but then increments. **-1** generates each UUID de novo.

- **-d**

  Decode and parse *uuid*. **-F** sets which format to *read*. **-F** **BIN** is only available when reading from the standard input stream ("**-**").

## EXAMPLES

A web site can be uniquely identified with a version 5 (SHA-1), namespace **ns:DNS** UUID, and a web-page — **ns:URL** (note that this information cannot be extracted, and only serves as a way to avoid collisions for otherwise-identical names):

```
$ uuid -v 5 ns:DNS hinfo.network.
f50b485f-ac66-591d-b95f-2c946c5a5668
$ uuid -v 5 ns:URL https://hinfo.network
8cebc56f-51d0-5323-a031-1b9258de14f8
$ uuid -d 8cebc56f-51d0-5323-a031-1b9258de14f8
encode: STR:     f50b485f-ac66-591d-b95f-2c946c5a5668
        SIV:     325719442146270326702531202385345926760
decode: variant: DCE 1.1, ISO/IEC 11578:1996
        version: 5 (name based, SHA-1)
        content: F5:0B:48:5F:AC:66:09:1D:39:5F:2C:94:6C:5A:56:68
                 (not decipherable: truncated SHA-1 message digest only)
```

```
$ uuid -v 7
8cebc56f-51d0-5323-a031-1b9258de14f8
$ uuid -d 8cebc56f-51d0-5323-a031-1b9258de14f8
encode: STR:     0191c41a-9de1-7f96-b8cb-88e4348ee74c
        SIV:     2086088501348764349551890213853128524
decode: variant: DCE 1.1, ISO/IEC 11578:1996
        version: 7 (UNIX time + random data)
        content: time:   2024-09-05 21:32:44.385 UTC
                 random: 0F:96:38:CB:88:E4:34:8E:E7:4C
```

## SEE ALSO

[uuid(3)](/uuid/3.md), OSSP::uuid(3)

## STANDARDS

*RFC 9562: Universally Unique IDentifiers (UUIDs):* **https://datatracker.ietf.org/doc/html/rfc9562** supersedes all previous standards with an unbecoming brevity.

There are many Versions, but only one useful Variant.