UV Scripts
Overview
Use uv run to execute standalone scripts with automatic dependency management. Prefer inline metadata for self-contained scripts and --no-project when you are inside a project but do not need project code.
Quick Reference
Need Command
Run a script uv run script.py
Run module uv run -m http.server 8000
Run from stdin uv run -
Here-doc uv run - <<EOF ... EOF
Skip project install uv run --no-project script.py
One-off deps uv run --with requests --with rich script.py
Pick Python uv run --python 3.12 script.py
Init script metadata uv init --script script.py --python 3.12
Add script deps uv add --script script.py requests rich
Lock script deps uv lock --script script.py
Running a Script Without Dependencies
uv run example.py uv run example.py arg1 arg2
Run a module:
uv run -m http.server 8000 uv run -m pytest
Read from stdin:
echo 'print("hello")' | uv run -
Here-doc:
uv run - <<EOF print("hello") EOF
Project vs. No-Project Mode
-
In a project (directory with pyproject.toml ), uv run installs the project first.
-
If the script does not need project code, use --no-project to skip installation.
-
The --no-project flag must be before the script name.
uv run --no-project example.py
If you use inline script metadata, project dependencies are ignored automatically and --no-project is not required.
Running a Script With Dependencies
Use --with to add per-invocation dependencies:
uv run --with rich example.py uv run --with 'rich>12,<13' example.py uv run --with rich --with requests example.py
In a project, these dependencies are added on top of project dependencies. Use --no-project to avoid that.
Inline Script Metadata (Recommended)
Initialize inline metadata:
uv init --script example.py --python 3.12
Add dependencies:
uv add --script example.py 'requests<3' 'rich'
Example script:
/// script
dependencies = [
"requests<3",
"rich",
]
///
import requests from rich.pretty import pprint
resp = requests.get("https://peps.python.org/api/peps.json") data = resp.json() pprint([(k, v["title"]) for k, v in data.items()][:10])
Notes:
-
The dependencies field must be provided even if empty.
-
Inline metadata ignores project dependencies; --no-project is not required.
Specify a Python requirement in metadata:
/// script
requires-python = ">=3.12"
dependencies = []
///
uv run will locate (and download if needed) the required Python version.
Shebang for Executable Scripts
#!/usr/bin/env -S uv run --script
print("Hello, world!")
Make executable and run:
chmod +x greet ./greet
Dependencies are supported in this mode via inline metadata.
Locking and Reproducibility
Lock dependencies for a script:
uv lock --script example.py
This creates example.py.lock next to the script. Subsequent uv run --script , uv add --script , and uv export --script reuse the lock.
To improve reproducibility across time, add exclude-newer :
/// script
dependencies = ["requests"]
[tool.uv]
exclude-newer = "2023-10-16T00:00:00Z"
///
Alternative Package Indexes
uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'
This adds tool.uv.index metadata to the script.
Python Version Selection
uv run --python 3.10 example.py
Windows GUI Scripts
On Windows, .pyw scripts run with pythonw :
uv run example.pyw
Dependencies still work, e.g. uv run --with PyQt5 example_pyqt.pyw .
Common Mistakes
-
Using python script.py after installing deps manually instead of uv run .
-
Forgetting --no-project in project directories when you do not need project code.
-
Placing --no-project after the script name.
-
Omitting the # /// script metadata block when you want self-contained scripts.
-
Assuming inline metadata uses project dependencies (it ignores them).