uuid.main

A uuidgen that ships with Python. Random output has nothing to demo live, so the examples call uuid.main() with a patched sys.argv to show the deterministic uuid3/uuid5 forms. -n takes a UUID or one of @dns, @url, @oid, @x500.

uuid functionPython 3.12+
Common call
python -m uuid
Returns
a new uuid4 printed as text
Replaces
uuidgen, or python -c "import uuid; print(uuid.uuid4())"
Watch out
uuid3/uuid5 need both -n and -N, or it exits with an error
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME]
→ None

Parameters

NameTypeRequiredDescription
-u, --uuiduuid1 | uuid3 | uuid4 | uuid5no (uuid4)Which function to call. 3.14 adds uuid6, uuid7 and uuid8.
-n, --namespacestrno (None)For uuid3/uuid5: a UUID string or @dns, @url, @oid, @x500.
-N, --namestrno (None)For uuid3/uuid5: the name to hash.

Return value

None — Prints one UUID to stdout; argument errors exit with status 2.

Common patterns

Random UUID in a shell
uuid4 is the default.
# shell:
# python -m uuid
Name-based UUID in a shell
Same result as uuid.uuid5(uuid.NAMESPACE_URL, "example.com").
# shell:
# python -m uuid -u uuid5 -n @url -N example.com
Several UUIDs (3.14: -C)
Before 3.14, loop in the shell or in Python.
# shell, 3.14+:
# python -m uuid -C 5
import uuid
for _ in range(5):
    print(uuid.uuid4())

Examples

1. uuid5 from the command line
import sys, uuid from unittest import mock with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '@dns', '-N', 'python.org']): uuid.main()
Returns
886313e1-3b8a-5372-9b90-0c9aee199e5d
2. uuid3 with @url
import sys, uuid from unittest import mock with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid3', '-n', '@url', '-N', 'https://example.com/']): uuid.main()
Returns
b9dcdff8-af4a-365d-8043-0f8361942709
3. A namespace given as a UUID
import sys, uuid from unittest import mock with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '6ba7b810-9dad-11d1-80b4-00c04fd430c8', '-N', 'python.org']): uuid.main()
Returns
886313e1-3b8a-5372-9b90-0c9aee199e5d
4. Same as calling uuid5
import uuid print(uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org'))
Returns
886313e1-3b8a-5372-9b90-0c9aee199e5d
5. Default output: one uuid4 line
import io, sys, uuid from contextlib import redirect_stdout from unittest import mock buf = io.StringIO() with mock.patch.object(sys, 'argv', ['uuid']), redirect_stdout(buf): uuid.main() uuid.UUID(buf.getvalue().strip()).version
Returns
4

Pitfalls

1. Forgetting -N (or -n) for uuid5
Without both, argparse prints "uuid5 requires a namespace and a name" to stderr and exits with status 2.
no name
import sys, uuid
from unittest import mock
with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '@dns']), mock.patch.object(sys, 'stderr'):
    try:
        uuid.main()
    except SystemExit as e:
        print('exit status', e.code)
exit status 2
with -N
import sys, uuid
from unittest import mock
with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '@dns', '-N', 'python.org']):
    uuid.main()
886313e1-3b8a-5372-9b90-0c9aee199e5d
2. Unknown namespace shortcut
Only @dns, @url, @oid and @x500 are shortcuts; anything else is parsed as a UUID string.
-n @email
import sys, uuid
from unittest import mock
with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '@email', '-N', 'ada']):
    uuid.main()
ValueError: badly formed hexadecimal UUID string
-n @url
import sys, uuid
from unittest import mock
with mock.patch.object(sys, 'argv', ['uuid', '-u', 'uuid5', '-n', '@url', '-N', 'mailto:ada@example.com']):
    uuid.main()
3d21f9ee-d85e-5a10-bda2-dff7da80567a

When to use

Use it
  • Generating an ID by hand in a terminal, CI script or Makefile
  • Computing a uuid5/uuid3 for a name without writing code
Reach for something else
  • Inside Python programs → call uuid.uuid4() / uuid.uuid5() directly
  • Python 3.11 and older → python -c "import uuid; print(uuid.uuid4())"

Notes

CPython impl
def main() in Lib/uuid.py builds an argparse parser; with uuid3/uuid5 it maps @dns/@url/@oid/@x500 to the NAMESPACE_* constants, else calls UUID(namespace), and prints the result
Version
Command-line usage was added in 3.12. 3.14 adds -C/--count and the uuid6, uuid7, uuid8 choices (docs.python.org 3.14)
Errors
Missing -n/-N for uuid3/uuid5 → parser.error, exit status 2; an invalid namespace string → ValueError traceback

FAQ

python -m uuid prints a random uuid4 (Python 3.12+). For a name-based one: python -m uuid -u uuid5 -n @dns -N example.com.