racurry UV Scripts
Corrections and conventions for writing Python scripts with UV inline metadata (PEP 723). Claude knows UV basics but consistently gets these details wrong.
Shebang Requires -S Flag
#!/usr/bin/env -S uv run --script
Not #!/usr/bin/env uv run --script — without -S, env treats uv run --script as a single argument and fails.
For scripts that should suppress UV's own output, use --quiet:
#!/usr/bin/env -S uv run --quiet --script
Empty Dependencies Must Be Explicit
The dependencies field is required even when empty:
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
Omitting dependencies causes UV to fail, even if you only need requires-python.
Complete Template
#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///