Inspect UUID Variants and Types with uuidparse

By the end of this guide, you will be able to classify UUIDs as they pass through a shell pipeline, see whether a value is random, time-based, name-based or invalid, and select output that will not surprise a script. The examples use the installed uuidparse command.

Prerequisites: a Linux shell and the uuid-runtime package, or another util-linux installation that provides uuidparse. Allow about 10 minutes. No elevated privileges are needed because the command only reads its arguments or standard input and does not alter UUIDs, files or services.

1. Check the local version and interface

Start by checking the executable that your shell will run. This matters because a package manager version and a manually installed binary can describe different behaviour.

command -v uuidparse
uuidparse --version
uuidparse --help

On the reference system, the manpage is from util-linux 2.39.3 and the packaged uuid-runtime version is 2.39.3-9ubuntu6.6. The executable found first in PATH reports util-linux 2.42.4, so the command checks below use that executable while staying within the options documented by the local manpage. If the first command points somewhere unexpected, fix PATH or invoke the intended binary by its full path before automating it.

2. Classify one UUID

Give the UUID as an argument. A version 4 UUID is normally a DCE-variant random identifier.

uuidparse 550e8400-e29b-41d4-a716-446655440000

Expected output is a heading followed by one row similar to this:

UUID                                  VARIANT TYPE       TIME
550e8400-e29b-41d4-a716-446655440000  DCE     random

The four displayed fields are the UUID, its variant, its type and a time value when one can be derived. The blank time field for a random UUID is expected. The variant describes the UUID layout family. The type describes how the identifier was made, where the format contains enough information to identify it.

3. Remove headings for a compact result

Use --noheadings when another command or a human-readable log does not need the column names.

uuidparse --noheadings 550e8400-e29b-41d4-a716-446655440000

Expected output:

550e8400-e29b-41d4-a716-446655440000  DCE  random

Do not parse the default spacing by position if you control both ends of a long-lived interface. Prefer JSON for software that can consume it, or explicitly select columns after checking the local help output.

4. Use JSON when a program will consume the result

The --json option returns one JSON document containing a uuids array. This keeps the field names visible and represents an unavailable time as JSON null.

uuidparse --json 550e8400-e29b-41d4-a716-446655440000

On the reference executable, the result includes:

{
   "uuids": [
      {
         "uuid": "550e8400-e29b-41d4-a716-446655440000",
         "variant": "DCE",
         "type": "random",
         "time": null
      }
   ]
}

Check that the output is valid JSON before handing it to a parser:

uuidparse --json 550e8400-e29b-41d4-a716-446655440000 | jq .

If jq is not installed, the command itself still produces JSON. The extra checker is optional and is not part of uuid-runtime.

5. Parse a batch from standard input

uuidparse accepts whitespace-separated values from standard input. This makes it useful after a command that emits one UUID per line.

printf '%s\n' \
  00000000-0000-0000-0000-000000000000 \
  6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  550e8400-e29b-41d4-a716-446655440000 |
  uuidparse --noheadings

Representative output is:

00000000-0000-0000-0000-000000000000  NCS
6ba7b810-9dad-11d1-80b4-00c04fd430c8  DCE  time-based  1998-02-04 22:13:53,151182+00:00
550e8400-e29b-41d4-a716-446655440000  DCE  random

The zero UUID is identified as the NCS variant with no ordinary type label in this output. The time-based example exposes a timestamp. Treat that timestamp as diagnostic information, not as a general-purpose event time: the UUID format and implementation determine what can be recovered.

Whitespace is the separator, so an accidental header, punctuation, or log prefix becomes another input value. Keep the producer's output limited to UUIDs, or validate and filter it before this step.

6. Handle invalid input without mistaking it for success

Try a known bad value when testing a pipeline.

printf '%s\n' not-a-uuid | uuidparse

The reference executable prints an invalid variant, type and time for that row:

UUID       VARIANT TYPE    TIME
not-a-uuid invalid invalid invalid

That row is a diagnostic result, not a repaired identifier. Do not pass it onwards as though classification succeeded. If invalid data must stop a job, inspect the command's exit status and the output policy on the exact util-linux version you deploy. Test the same full pipeline in your environment instead of assuming that row formatting alone is a sufficient error signal.

Do not use uuidparse to generate identifiers. Its job is to inspect input. For generation, use a separately verified tool such as the installed uuidgen command, then feed its output to uuidparse if you need a classification check.

7. Select columns only after checking their names

The --output option limits the displayed columns. The local help lists UUID, VARIANT, TYPE and TIME. Ask the command for the exact syntax on the machine where the script will run, then select only the fields you need.

uuidparse --help
uuidparse --output UUID,VARIANT,TYPE 550e8400-e29b-41d4-a716-446655440000

Column-list syntax can vary with util-linux releases and builds, so the help check is part of the safe procedure. If this command rejects the list, do not guess a replacement in production: read the displayed column syntax and adjust the list for that version. The --raw option is another presentation mode; use it only after inspecting its output with representative values.