Generate Random and Repeatable UUIDs with uuidgen

You will finish with commands for creating one-off UUIDs and repeatable UUIDs derived from a namespace and name. You will also check which uuidgen executable is actually running, because the local command and the installed manpage can come from different util-linux versions.

Allow about ten minutes. You need a Linux shell and the uuidgen command. The examples are ordinary user commands. They do not need sudo, and they do not alter files, services or persistent configuration.

The examples below were checked with the local executable, util-linux 2.42.4. The local uuidgen(1) manpage is from util-linux 2.39.3 and the Debian package uuid-runtime is also 2.39.3-9ubuntu6.6. Keep that distinction in mind when a system has more than one installation.

1. Check the executable and version

Start with a read-only check. This catches a common distraction: reading one manpage while your shell runs another 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 this machine, the executable is a Linuxbrew installation and is not owned by the Debian package. Your paths and versions may differ. If command -v shows an unexpected path, inspect that installation before relying on its help output or changing 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 will differ on every run. The command requires a high-quality operating-system random source. The output has the familiar hexadecimal and hyphenated UUID form, but do not treat its text as a password or as a way to store a secret in a command history.

With no option, uuidgen normally chooses a random-based UUID when a high-quality random generator is available. Otherwise it chooses a time-based UUID. Use --random when the method matters and you want the choice to be visible in a script.

Check that 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 stores the output without the trailing newline. Quote the variable when using it. There is no undo operation because uuidgen only prints a value; undo the later database, file or API operation if that value has already been used elsewhere.

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 based on the system clock and the system's Ethernet hardware address when one is present. That makes it different from the mostly random form. A time-based UUID can reveal information about how it was produced, so do not select it merely because the output looks familiar.

Neither method guarantees that a different application will never choose 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 a database uniqueness constraint, keep that constraint too.

4. Create a repeatable UUID from a namespace and name

A hash-based UUID is useful when the same logical input must produce the same identifier. Choose either --sha1 or --md5, then provide 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 requires 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 they are identifiers rather than secrets, nonces or access tokens. The manual describes this predictability as useful for handles where the original value should not be disclosed directly, but that does not make the UUID 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, use the executable you already checked:

$ uuidgen --help
Usage:
 uuidgen [options]

Create a new UUID value.

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