uv-scripts

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 = []
# ///