Inspect UUID Variants and Types with uuidparse

A pipeline that swallows a malformed UUID silently is worse than one that fails loudly, and uuidparse is the tool that tells you which is which. You will learn to classify a UUID as random, time-based, name-based or invalid, and pick output that will not surprise a script.

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: 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 your shell will actually run. 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 is 2.39.3-9ubuntu6.6, but the executable found first in PATH reports util-linux 2.42.4. The commands below use that executable while staying within the options the local manpage documents. If your first command points somewhere unexpected, fix PATH or call the intended binary by its full path before you automate anything.

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 like this:

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

• UUID. The value you passed in.
• VARIANT. The layout family the UUID belongs to.
• TYPE. How the identifier was made, where the format carries enough information to tell.
• TIME. A time value when one can be derived; blank here is expected for a random UUID.

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 column position if you control both ends of a long-lived interface. Prefer JSON for anything 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 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 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, which makes it useful straight 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:

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 comes back as the NCS variant with no ordinary type label. The time-based row exposes a timestamp: treat it as diagnostic information, not a general-purpose event time, since the UUID format and implementation decide what can actually be recovered.

Whitespace is the separator, so an accidental header, stray 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 onward as though classification succeeded. If invalid data must stop a job, check the command's exit status and output policy on the exact util-linux version you deploy, and test the full pipeline in your environment rather than assuming 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 uuidgen, 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 between util-linux releases and builds, so the help check is part of the safe procedure. If the command rejects the list, do not guess a replacement in production: read the displayed column syntax and adjust for that version. --raw is another presentation mode; check its output with representative values before you rely on it.