UUID(1)

📦
version 1.6.6 · 7 versions
, in alpine 3.24, ubuntu resolute, ubuntu stonking

💖 UUID 💖

okay bestie, listen. you've found the manual page for uuid — that's UUID(1), living its best life in the General Commands Manual. she generates, converts, and decodes Universally Unique IDentifiers, and she does it with main character energy every single time. no cap. 🎀

✨ NAME ✨

uuid — generate, convert, and decode Universally Unique IDentifiers 💅 that's the whole résumé, and honestly? iconic.

🦋 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 🌸

so like, by default uuid generates a UUID (Universally Unique Identifier) of a version you pick with -v (defaults to 1), and spits it out in the canonical STRing format. default behaviour, zero drama.

when you hit her with -d, she decodes uuid — or reads it in from the standard input stream if you hand her "-" — and you get 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, alternatively:

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)

now, a UUID is a 128-bit (16-byte) number whose format (aka the method of generation) makes it very likely to be unique, both spatially and temporally. which is exactly why they're so good at identifying anything from ephemera like database queries all the way up to databases themselves. range, honestly. 👑

the three principal -Formats 🫶

  • STRing — 01234567-890a-bcde-f012-3456789abcde (a hexadecimal string broken up by dashes)
  • SIV (Single Integer Value) — a 128-bit decimal integer
  • BINary or "raw" — the 16 bytes of the UUID in big endian order (most significant first)

UUIDs come in a few -versions 🦋

  • 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. 🔥 fr fr, listen to her.
  • 3 — hashes the "namespace" (first argument, either a STRing-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 she understands when generating version 3 and 5 UUIDs 🌈

  • uuid — (any valid STRingified 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 — literally just -F BIN. a shortcut, a vibe, a whole mood.
  • -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 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)

and check it, version 7 doing her little thing:

$ uuid -v 7
0191c41a-9de1-7f96-b8cb-88e4348ee74c
$ uuid -d 0191c41a-9de1-7f96-b8cb-88e4348ee74c
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 🌟

👑 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. iykyk. ✨

and that's the whole page, bestie!! this one comes from ossp-uuid 1.6.6, dated December 8, 2025 — thanks for reading, mwah 💋🫶 go generate something unique.

📦 where this page comes from