Generate Random and Repeatable UUIDs with uuidgen

uuidgen looks like a one-trick command until you need the same identifier twice. This guide covers one-off random UUIDs, deliberate time-based ones, and repeatable hash-based ones from a namespace and name, plus the version check that catches a stale copy earlier in your PATH. This installed executable and its uuidgen(1) manpage do not always come from the same version, so that check matters more than usual.

Allow about ten minutes. You need a Linux shell and the uuidgen command. Every example is an ordinary user command: none need sudo, and none alter files, services or persistent configuration.

1. Check the executable and version

Start with a read-only check. This catches a common distraction: reading one manpage while your shell runs a completely different copy found earlier in PATH.

$ command -v uuidgen
/home/linuxbrew/.linuxbrew/bin/uuidgen
$ uuidgen --version
uuidgen from util-linux 2.42.4
$ dpkg-query -W -f='${Package} ${Version}\n' uuid-runtime
uuid-runtime 2.39.3-9ubuntu6.6

On the reference machine, the executable is a Linuxbrew installation and is not owned by the Debian package at all. Your paths and versions may differ. If command -v shows an unexpected path, inspect that installation before trusting its help output or touching your shell configuration.

2. Generate a normal random UUID

For an ordinary identifier, ask for a random-based UUID explicitly:

$ uuidgen --random
40e3feb9-4a52-41dc-b508-12ef06f3d2f1

• The value differs every run. It needs a high-quality operating-system random source to do that.
• It is not a secret. The output has the familiar hexadecimal, hyphenated UUID shape, but do not treat it as a password or stash it in a command history as one.
• No option means a guess. With nothing specified, uuidgen normally picks a random-based UUID when a high-quality random generator is available, and a time-based one otherwise. Use --random explicitly when the method matters and you want the choice visible in a script.

Check the result is non-empty before passing it to another command:

$ id_value=$(uuidgen --random)
$ test -n "$id_value" && printf 'generated: %s\n' "$id_value"
generated: 7a7d4cb7-1e4e-4b83-9a09-4f48d3c1165a

Command substitution strips the trailing newline, so quote the variable when you use it. There is no undo for uuidgen itself: it only prints a value. If that value has already gone into a database, file or API call, undo the operation that used it, not the command that generated it.

3. Generate a time-based UUID when you need that method

Use --time to request a time-based UUID:

$ uuidgen --time
d5d28a18-ba93-11f1-97d3-901b0edaccef

This method is built from the system clock and, when present, the machine's Ethernet hardware address, which makes it different from the mostly random form. A time-based UUID can reveal something about how it was produced, so do not pick it just because the output looks familiar.

Neither method guarantees another application somewhere will never pick the same value. The practical guarantee is that a UUID can reasonably be treated as unique among values generated locally and elsewhere. If your application needs an actual uniqueness guarantee, keep the database constraint too.

4. Create a repeatable UUID from a namespace and name

A hash-based UUID earns its keep when the same logical input must always produce the same identifier. Choose --sha1 or --md5, then supply both a namespace and a name:

$ uuidgen --sha1 --namespace @dns --name 'www.example.com'
2ed6657d-e927-568b-95e1-2665a8aea6a2
$ uuidgen --sha1 --namespace @dns --name 'www.example.com'
2ed6657d-e927-568b-95e1-2665a8aea6a2

The built-in namespace aliases are @dns, @url, @oid and @x500; you can also pass a UUID as the namespace. The name is an arbitrary string. Keep the namespace, algorithm, byte encoding and name spelling unchanged if another process must reproduce the result.

Use --md5 in the same shape when compatibility with an existing version 3 UUID scheme demands it:

$ uuidgen --md5 --namespace @dns --name 'www.example.com'
5df41881-3aed-3515-88a7-2f4a814cf09e

These values are predictable: anyone who knows the namespace, algorithm and name can calculate them, so treat them as identifiers rather than secrets, nonces or access tokens. The manual calls this predictability useful for handles where the original value should not be disclosed directly, but that is not the same as being cryptographically secret.

5. Validate failures instead of guessing

A hash-based UUID needs both required inputs. Test the failure path without changing anything:

$ uuidgen --sha1 --namespace @dns
uuidgen: --namespace requires --name argument
Try 'uuidgen --help' for more information.
$ printf 'exit status: %s\n' "$?"
exit status: 1

A non-zero status is the useful signal for a script. Capture it immediately, before another command overwrites $?. Quote names containing spaces or shell metacharacters, and prefer fixed arguments over interpolating untrusted text into the option area.

If you need the local option contract, ask the executable you already checked:

$ uuidgen --help
Usage:
 uuidgen [options]

Create a new UUID value.

The full help text can list options newer than the compressed manpage. Follow the documentation that matches your executable, and treat the manpage as a versioned reference rather than assuming every installation has identical flags.