{{tag>[cli uuid uuidgen util-linux]}}

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

===== Summary =====
  * 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을 사용한다.

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

<code bash>
sudo apt update
sudo apt install uuid-runtime
</code>

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

<code bash>
sudo dnf install util-linux
</code>

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

<code bash>
brew install util-linux
"$(brew --prefix util-linux)/bin/uuidgen" --version
</code>

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

<code powershell>
New-Guid
</code>

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

<code bash>
command -v uuidgen
uuidgen --version
</code>

===== Usage =====
<code bash>
uuidgen [OPTIONS]
</code>

  * ''<color #c3c3c3>**uuidgen**</color> <color #22b14c>[OPTIONS]</color>'': UUID 한 개를 생성한다.
  * ''<color #c3c3c3>**uuidgen**</color> <color #22b14c>**--sha1 --namespace**</color> <color #7092be>NAMESPACE</color> <color #22b14c>**--name**</color> <color #7092be>NAME</color>'': namespace와 name으로 결정적인 UUID를 생성한다.

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

===== Examples =====
==== 기본 random UUID 생성 ====
<code bash>
uuidgen
uuidgen --random
</code>

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

==== shell 변수에 저장 ====
<code bash>
request_id=$(uuidgen) || exit 1
printf 'request_id=%s\n' "$request_id"
</code>

==== 같은 입력에서 같은 UUID 생성 ====
<code bash>
uuidgen --sha1 --namespace @dns --name 'www.example.com'
uuidgen --sha1 --namespace @url --name 'https://www.example.com/resource'
</code>

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

==== 여러 UUID 생성 ====
최신 util-linux에서는 ''--count''를 사용할 수 있다.

<code bash>
uuidgen --random --count 5
</code>

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

<code bash>
for _ in 1 2 3 4 5; do
    uuidgen --random || exit 1
done
</code>

==== 시간순 정렬 가능한 UUID 생성 ====
최신 util-linux에서 version 7 UUID를 생성한다.

<code bash>
uuidgen --time-v7
</code>

<note important>
''--time'', ''--time-v6'', ''--time-v7'', ''--count''의 지원 여부는 설치된 util-linux version에 따라 다르다. 배포 script에서 사용하기 전에 ''uuidgen --help''로 확인한다.
</note>

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

<code bash>
command -v uuidgen
uuidgen --version
uuidgen --help
</code>

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

<code bash>
"$(brew --prefix util-linux)/bin/uuidgen" --time-v7
</code>

==== 같은 name인데 결과가 다름 ====
''--namespace'', ''--name'', hash algorithm이 모두 같아야 같은 name-based UUID가 생성된다. ''@dns''와 ''@url''은 서로 다른 namespace다.

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

<code bash>
uuidgen --random | uuidparse
</code>

===== Compatibility =====
  * 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하는 정책을 정한다.

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

++++ 기존 page의 uuidgen --help 기록 (version 미상) |
<code text>
❯ 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).
</code>
++++

++++ uuidgen --help (util-linux 2.32.1) |
<code text>
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).
</code>
++++

===== See Also =====
  * [[:powershell]]
  * [[https://man7.org/linux/man-pages/man1/uuidgen.1.html|util-linux uuidgen(1) manual]]
  * [[https://packages.debian.org/stable/uuid-runtime|Debian uuid-runtime package]]
  * [[https://packages.fedoraproject.org/pkgs/util-linux/util-linux/|Fedora util-linux package]]
  * [[https://formulae.brew.sh/formula/util-linux|Homebrew Formulae: util-linux]]

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

{{indexmenu>.#1|js}}