| name | uv-usage |
| description | Provides concise guidance for using uv (Python package manager), including project workflows, pip-compatible commands, Python version management, and PEP 723 inline script dependencies. Use when users mention uv, uv run, inline dependencies, PEP 723, or Python dependency/project management. |
uv Usage
Quick start
Use uv as a fast, unified tool for Python projects:
- Initialize a project:
uv init
- Add deps:
uv add <package>
- Sync env:
uv sync
- Run commands:
uv run <cmd>
uv add updates uv.lock automatically; use uv lock when you need to re-lock after manual pyproject.toml edits.
Inline dependencies (PEP 723 scripts)
Use inline metadata so a script runs standalone with uv run <script-file>.
Steps
- Add a
# /// script block at the top of the file.
- Set
requires-python and dependencies.
- Run the script with
uv run <script-file>.
- Add or remove inline deps with
uv add --script and uv remove --script.
Template
import requests
from rich import print
print(requests.get("https://api.github.com/repos/astral-sh/uv").status_code)
Commands
uv run script.py
uv add --script script.py beautifulsoup4
uv remove --script script.py rich
Pip-compatible commands
Use these for drop-in workflows or legacy projects:
uv pip install <package>
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
Python versions and environments
uv python install 3.12
uv python pin 3.12
uv venv --python 3.12
uv run --python 3.12 -- python -V
Examples
New project
uv init demo
cd demo
uv add ruff
uv run ruff check .
Standalone script with inline deps
uv run script.py
Notes
- uv offers pip-compatible commands, but behavior can differ in edge cases.
- Use
uvx <tool> (alias for uv tool run) to run tools ephemerally without installing them globally.
- Prefer project workflow (
uv add, uv sync) for new work, and run uv lock when re-locking after manual pyproject.toml changes.