uuidgen

uuidgen은 새 UUID(Universally Unique Identifier)를 생성해 stdout에 출력하는 command-line 도구다. Linux의 util-linux 구현은 libuuid를 사용하며 random, time-based, name-based UUID를 지원한다.

• argument 없이 실행하면 고품질 random source가 있는 환경에서 random-based UUID(UUID version 4)를 생성한다.
• 같은 namespace와 name에서 항상 같은 값을 얻으려면 –md5(version 3) 또는 –sha1(version 5)을 사용한다.
• 최신 util-linux는 timestamp 순 정렬에 유리한 UUID version 6과 version 7도 지원한다.
• UUID는 식별자이지 secret이나 인증 token이 아니다. 예측 가능성이 보안에 영향을 주는 용도에는 별도의 cryptographically secure token을 사용한다.

uuidgen은 uuid-runtime package에 포함된다. 이 package에는 time-based UUID의 고속·동시 생성을 보조하는 uuidd daemon도 함께 포함될 수 있다.

sudo apt update
sudo apt install uuid-runtime

Fedora에서는 util-linux package가 uuidgen을 제공한다.

sudo dnf install util-linux

macOS에는 별도 설치 없이 사용할 수 있는 BSD 계열 /usr/bin/uuidgen이 기본 제공되지만 util-linux 구현과 option이 다르다. util-linux 동작이 필요하면 Homebrew formula를 설치할 수 있다. 이 formula는 keg-only이므로 명시적인 경로로 실행한다.

brew install util-linux
"$(brew --prefix util-linux)/bin/uuidgen" --version

util-linux project는 공식 native Windows 또는 WinGet package를 제공하지 않는다. PowerShell에서는 New-Guid를 사용하고, util-linux와 같은 CLI가 필요하면 WSL distribution 안에서 uuid-runtime 또는 util-linux를 설치한다.

New-Guid

util-linux 구현은 다음과 같이 version과 실행 경로를 확인한다. macOS 기본 구현은 –version을 지원하지 않는다.

command -v uuidgen
uuidgen --version

uuidgen [OPTIONS]

• uuidgen [OPTIONS]: UUID 한 개를 생성한다.
• uuidgen –sha1 –namespace NAMESPACE –name NAME: namespace와 name으로 결정적인 UUID를 생성한다.

• -r, –random: random-based UUID(version 4)를 생성한다.
• -t, –time: system clock과 사용 가능한 hardware address를 바탕으로 time-based UUID(version 1)를 생성한다.
• -6, –time-v6: timestamp에 따라 lexicographical sort가 가능한 time-based UUID(version 6)를 생성한다. 오래된 util-linux에서는 지원하지 않는다.
• -7, –time-v7: timestamp에 따라 lexicographical sort가 가능한 time-based UUID(version 7)를 생성한다. 오래된 util-linux에서는 지원하지 않는다.
• -m, –md5: name-based UUID 생성에 MD5를 사용해 version 3 UUID를 만든다.
• -s, –sha1: name-based UUID 생성에 SHA-1을 사용해 version 5 UUID를 만든다.
• -n, –namespace NAMESPACE: name-based UUID의 namespace UUID를 지정한다. UUID 값 또는 well-known alias @dns, @url, @oid, @x500을 사용할 수 있다.
• -N, –name NAME: name-based UUID에 hash할 name을 지정한다.
• -x, –hex: –name 값을 일반 문자열이 아닌 hexadecimal string으로 해석한다.
• -C, –count NUM: UUID를 여러 개 생성한다. 이 option은 util-linux version에 따라 없을 수 있다.
• -h, –help: help를 표시하고 종료한다.
• -V, –version: util-linux version을 표시하고 종료한다.

uuidgen
uuidgen --random

argument 없는 실행은 일반적인 일회성 식별자 생성에 적합하다. 출력 끝에는 newline이 포함된다.

request_id=$(uuidgen) || exit 1
printf 'request_id=%s\n' "$request_id"

uuidgen --sha1 --namespace @dns --name 'www.example.com'
uuidgen --sha1 --namespace @url --name 'https://www.example.com/resource'

name-based UUID는 입력이 같으면 결과도 같다. 이는 password hashing이나 secret 생성 방식이 아니다.

최신 util-linux에서는 –count를 사용할 수 있다.

uuidgen --random --count 5

호환성이 더 중요하거나 –count를 지원하지 않는 구현에서는 shell loop를 사용한다.

for _ in 1 2 3 4 5; do
    uuidgen --random || exit 1
done

최신 util-linux에서 version 7 UUID를 생성한다.

uuidgen --time-v7

설치된 util-linux가 오래되었거나 macOS 기본 uuidgen을 실행 중일 수 있다. 실행 경로, version, help를 확인한다.

command -v uuidgen
uuidgen --version
uuidgen --help

macOS에서 Homebrew util-linux를 설치했다면 keg-only 경로의 binary를 직접 실행한다.

"$(brew --prefix util-linux)/bin/uuidgen" --time-v7

–namespace, –name, hash algorithm이 모두 같아야 같은 name-based UUID가 생성된다. @dns와 @url은 서로 다른 namespace다.

util-linux의 uuidparse가 설치되어 있으면 UUID의 variant, type, timestamp 정보를 확인할 수 있다.

uuidgen --random | uuidparse

• Linux util-linux와 macOS 기본 uuidgen은 이름은 같지만 option 집합과 출력 대소문자가 다를 수 있다.
• UUID version 6과 7은 최신 util-linux에서만 사용할 수 있으므로 구형 distribution을 지원하는 script에는 version check나 fallback이 필요하다.
• –count는 구형 util-linux에서 지원하지 않는다. 기존 page에 기록돼 있던 util-linux help에는 –count가 표시됐지만 현재 로컬 util-linux 2.32.1 binary에는 포함되지 않아 build·distribution 차이도 확인해야 한다.
• name-based UUID의 @dns, @url, @oid, @x500 alias는 util-linux 기능이며 macOS 기본 구현에 그대로 적용되지 않는다.
• UUID 문자열 비교나 저장에서는 입력 대소문자를 허용하되 canonical form을 일관되게 normalize하는 정책을 정한다.

기존 page에 기록된 version 미상의 help와 현재 로컬 환경에서 확인한 util-linux 2.32.1 출력을 각각 보존한다. 최신 version의 –time-v6, –time-v7, –count는 아래 출력에 없을 수 있다.

기존 page의 uuidgen --help 기록 (version 미상)

❯ uuidgen --help
 
Usage:
 uuidgen [options]
 
Create a new UUID value.
 
Options:
 -r, --random          generate random-based uuid
 -t, --time            generate time-based uuid
 -n, --namespace <ns>  generate hash-based uuid in this namespace
                        available namespaces: @dns @url @oid @x500
 -N, --name <name>     generate hash-based uuid from this name
 -m, --md5             generate md5 hash
 -C, --count <num>     generate more uuids in loop
 -s, --sha1            generate sha1 hash
 -x, --hex             interpret name as hex string
 
 -h, --help          display this help
 -V, --version       display version
 
For more details see uuidgen(1).

uuidgen --help (util-linux 2.32.1)

Usage:
 uuidgen [options]
 
Create a new UUID value.
 
Options:
 -r, --random        generate random-based uuid
 -t, --time          generate time-based uuid
 -n, --namespace ns  generate hash-based uuid in this namespace
 -N, --name name     generate hash-based uuid from this name
 -m, --md5           generate md5 hash
 -s, --sha1          generate sha1 hash
 -x, --hex           interpret name as hex string
 
 -h, --help       display this help
 -V, --version    display version
 
For more details see uuidgen(1).

• powershell
• util-linux uuidgen(1) manual
• Debian uuid-runtime package
• Fedora util-linux package
• Homebrew Formulae: util-linux

• codex:: 2026-08-17 기존 uuidgen command와 option 기록을 보존하면서 설치, UUID type, 최신 option, 예시, 호환성, troubleshooting 문서를 확장했다.