Uv Script

UV Self-Contained Scripts

Create Python scripts with inline dependency declarations using the PEP 723 format. Dependencies are managed directly in the script file, making scripts portable and reproducible.

Creating a new script

Initialize a script with inline metadata:

uv init --script example.py --python 3.12

This creates a script with PEP 723 metadata block at the top.

Adding dependencies

Add dependencies directly to the script:

uv add --script example.py 'requests<3' 'rich'

This adds dependencies to the inline metadata:

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

Running scripts

Execute with uv run:

uv run example.py

Pass arguments normally:

uv run example.py arg1 arg2

For temporary dependencies without modifying the script:

uv run --with rich example.py

Python version requirements

Specify Python version in the metadata:

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///

Or request at runtime:

uv run --python 3.10 example.py

Making scripts executable

Add shebang to make scripts standalone:

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["requests"]
# ///

import requests
# ... rest of script

Then make executable:

chmod +x script.py
./script.py

Locking dependencies

Lock dependencies for reproducibility:

uv lock --script example.py

Creates an adjacent .lock file that ensures consistent dependency versions across runs.

Important notes

Project isolation: When using inline script metadata, project dependencies are ignored even if run within a project directory. The script's dependencies take precedence.

GUI scripts on Windows: Use .pyw extension for GUI scripts that should run with pythonw:

uv run example.pyw

Custom package indexes: Specify alternative indexes when adding dependencies:

uv add --index "https://example.com/simple" --script example.py 'package'

Reproducibility: Add exclude-newer to limit package versions by date:

# /// script
# dependencies = ["requests"]
#
# [tool.uv]
# exclude-newer = "2023-10-16T00:00:00Z"
# ///

Workflow

1. Initialize script: uv init --script name.py
2. Add dependencies: uv add --script name.py 'package'
3. Write your code
4. Run: uv run name.py
5. (Optional) Lock: uv lock --script name.py for reproducibility
6. (Optional) Add shebang and chmod +x to make executable