tools-only uv CLI Reference
Complete command reference for uv - the Python package and project manager.
Command Structure
uv [OPTIONS] <COMMAND>
Top-Level Commands
| Command | Description |
|---|---|
uv init |
Create a new project |
uv add |
Add dependencies to the project |
uv remove |
Remove dependencies from the project |
uv sync |
Update the project's environment |
uv lock |
Update the project's lockfile |
uv run |
Run a command or script |
uv tree |
Display the project's dependency tree |
uv export |
Export the project's lockfile to alternate formats |
uv version |
Read or update the project's version |
uv format |
Format Python code in the project |
uv tool |
Run and install commands provided by Python packages |
uv python |
Manage Python versions and installations |
uv pip |
Manage Python packages with pip-compatible interface |
uv venv |
Create a virtual environment |
uv build |
Build Python packages into distributions |
uv publish |
Upload distributions to an index |
uv cache |
Manage uv's cache |
uv auth |
Manage authentication |
uv self |
Manage the uv executable |
uv help |
Display documentation for a command |
Project Commands
uv init
Create a new project.
uv init [OPTIONS] [PATH]
Options:
| Option | Description |
|---|---|
--name <NAME> |
Project name (defaults to directory name) |
--package |
Create a Python package (default) |
--app |
Create an application project |
--lib |
Create a library project |
--script |
Create a standalone script with inline metadata |
--python <VERSION> |
Python version requirement |
--no-readme |
Skip README.md creation |
--no-pin-python |
Don't create .python-version |
--build-backend <BACKEND> |
Build backend (hatchling, flit-core, etc.) |
--vcs <VCS> |
Initialize version control (git, none) |
Examples:
uv init my-project
uv init --lib my-library
uv init --app --python 3.12 my-app
uv init --script example.py
uv add
Add dependencies to the project.
uv add [OPTIONS] <PACKAGES>...
Options:
| Option | Description |
|---|---|
--dev |
Add to development dependencies |
--group <GROUP> |
Add to specific dependency group |
--optional <EXTRA> |
Add as optional dependency (extra) |
--script <SCRIPT> |
Add to inline script metadata |
--editable |
Install as editable package |
--no-sync |
Don't sync after adding |
--frozen |
Don't update lockfile |
--locked |
Assert lockfile unchanged |
--upgrade-package <PKG> |
Upgrade specific package |
--index <URL> |
Package index for this dependency |
--python <VERSION> |
Python version for resolution |
Examples:
uv add requests flask
uv add "httpx>=0.20,<1.0"
uv add --dev pytest ruff mypy
uv add --group test pytest-cov
uv add --optional api fastapi uvicorn
uv add --script example.py pandas
uv add "git+https://github.com/user/repo"
uv add torch --index https://download.pytorch.org/whl/cpu
uv remove
Remove dependencies from the project.
uv remove [OPTIONS] <PACKAGES>...
Options:
| Option | Description |
|---|---|
--dev |
Remove from development dependencies |
--group <GROUP> |
Remove from specific group |
--optional <EXTRA> |
Remove from optional dependencies |
--script <SCRIPT> |
Remove from inline script metadata |
--no-sync |
Don't sync after removing |
Examples:
uv remove requests
uv remove --dev pytest
uv remove --group test pytest-cov
uv sync
Update the project's environment.
uv sync [OPTIONS]
Options:
| Option | Description |
|---|---|
--frozen |
Don't update lockfile |
--locked |
Assert lockfile unchanged |
--no-dev |
Exclude dev dependencies |
--only-dev |
Only dev dependencies |
--group <GROUP> |
Include specific group |
--no-group <GROUP> |
Exclude specific group |
--all-groups |
Include all groups |
--no-default-groups |
Exclude default groups |
--extra <EXTRA> |
Include optional dependency |
--all-extras |
Include all optional dependencies |
--no-install-project |
Don't install the project itself |
--no-install-workspace |
Don't install workspace members |
--no-editable |
Install as non-editable |
--exact |
Remove extraneous packages |
--inexact |
Keep extraneous packages |
--python <VERSION> |
Python version |
Examples:
uv sync
uv sync --locked
uv sync --no-dev --all-extras
uv sync --group test --group lint
uv sync --no-install-project # Dependencies only (Docker caching)
uv lock
Update the project's lockfile.
uv lock [OPTIONS]
Options:
| Option | Description |
|---|---|
--check |
Check if lockfile is up-to-date |
--upgrade |
Upgrade all packages |
--upgrade-package <PKG> |
Upgrade specific package |
--script <SCRIPT> |
Lock script dependencies |
--python <VERSION> |
Python version |
Examples:
uv lock
uv lock --check # CI validation
uv lock --upgrade
uv lock --upgrade-package requests
uv lock --script example.py
uv run
Run a command or script in the project environment.
uv run [OPTIONS] [COMMAND]...
Options:
| Option | Description |
|---|---|
--with <PKG> |
Add temporary dependency |
--with-requirements <FILE> |
Add temporary requirements |
--module, -m |
Run Python module |
--script |
Run as script |
--isolated |
Run in isolated environment |
--no-sync |
Don't sync environment |
--no-project |
Ignore project context |
--frozen |
Don't update lockfile |
--locked |
Assert lockfile unchanged |
--active |
Prefer active virtual environment |
--env-file <FILE> |
Load .env file |
--python <VERSION> |
Python version |
--all-extras |
Include all optional dependencies |
--extra <EXTRA> |
Include specific extra |
--group <GROUP> |
Include specific group |
--no-dev |
Exclude dev dependencies |
Examples:
uv run python script.py
uv run pytest -v
uv run --with pandas python analyze.py
uv run -m my_module
uv run --isolated ruff check .
uv run --env-file .env.local python app.py
echo 'print("hello")' | uv run -
uv tree
Display the project's dependency tree.
uv tree [OPTIONS]
Options:
| Option | Description |
|---|---|
--depth <N> |
Maximum display depth |
--package <PKG> |
Focus on specific package |
--prune <PKG> |
Prune specific packages |
--invert |
Show reverse dependencies |
--no-dev |
Exclude dev dependencies |
Examples:
uv tree
uv tree --depth 2
uv tree --package requests
uv tree --invert --package urllib3
uv export
Export the lockfile to alternate formats.
uv export [OPTIONS]
Options:
| Option | Description |
|---|---|
--format <FORMAT> |
Output format (requirements-txt, pylock.toml) |
--output-file, -o <FILE> |
Output file path |
--no-hashes |
Exclude hashes |
--no-dev |
Exclude dev dependencies |
--all-extras |
Include all extras |
--extra <EXTRA> |
Include specific extra |
Examples:
uv export --format requirements-txt -o requirements.txt
uv export --format pylock.toml
uv export --format cyclonedx1.5 -o sbom.json
Python Management Commands
uv python install
Install Python versions.
uv python install [OPTIONS] [VERSIONS]...
Options:
| Option | Description |
|---|---|
--default |
Install as default (python, python3 executables) |
--reinstall |
Reinstall existing versions |
--preview |
Include preview releases |
Examples:
uv python install
uv python install 3.12
uv python install 3.11 3.12 3.13
uv python install pypy
uv python install 3.12 --default
uv python list
List available and installed Python versions.
uv python list [OPTIONS] [VERSION]
Options:
| Option | Description |
|---|---|
--only-installed |
Show only installed versions |
--all-versions |
Include all patch versions |
--all-platforms |
Show downloads for all platforms |
Examples:
uv python list
uv python list --only-installed
uv python list 3.12
uv python list pypy
uv python pin
Pin Python version for the project.
uv python pin [OPTIONS] <VERSION>
Options:
| Option | Description |
|---|---|
--global |
Pin globally (user-level) |
--resolved |
Pin exact resolved version |
Examples:
uv python pin 3.12
uv python pin --global 3.12
uv python pin 3.12.5 --resolved
uv python find
Find Python executable.
uv python find [OPTIONS] [VERSION]
Options:
| Option | Description |
|---|---|
--system |
Ignore virtual environments |
--no-project |
Ignore project requirements |
Examples:
uv python find
uv python find ">=3.11"
uv python find 3.12
uv python upgrade
Upgrade Python installations.
uv python upgrade [OPTIONS] [VERSIONS]...
Examples:
uv python upgrade 3.12 # Upgrade to latest 3.12.x
uv python upgrade # Upgrade all installed
uv python uninstall
Uninstall Python versions.
uv python uninstall <VERSIONS>...
Examples:
uv python uninstall 3.11
uv python uninstall 3.11 3.12
Tool Commands
uv tool run (uvx)
Run a tool without installing.
uvx [OPTIONS] <COMMAND>...
uv tool run [OPTIONS] <COMMAND>...
Options:
| Option | Description |
|---|---|
--from <PKG> |
Package to run from |
--with <PKG> |
Additional dependencies |
--python <VERSION> |
Python version |
--isolated |
Ignore installed version |
Examples:
uvx ruff check .
uvx black --check .
uvx --from httpie http https://api.example.com
uvx ruff@0.5.0 check .
uvx --with mkdocs-material mkdocs build
uvx --python 3.12 mypy .
uv tool install
Install a tool globally.
uv tool install [OPTIONS] <PACKAGE>
Options:
| Option | Description |
|---|---|
--with <PKG> |
Additional packages |
--with-editable <PKG> |
Additional editable packages |
--python <VERSION> |
Python version |
--force |
Overwrite existing executables |
--reinstall |
Reinstall if already installed |
Examples:
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install ruff --python 3.12
uv tool install mkdocs --with mkdocs-material
uv tool list
List installed tools.
uv tool list [OPTIONS]
Options:
| Option | Description |
|---|---|
--show-paths |
Show executable paths |
uv tool upgrade
Upgrade installed tools.
uv tool upgrade [OPTIONS] [TOOL]
Options:
| Option | Description |
|---|---|
--all |
Upgrade all tools |
--upgrade-package <PKG> |
Upgrade specific dependency |
--reinstall |
Reinstall packages |
Examples:
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall
Uninstall a tool.
uv tool uninstall <TOOL>
uv tool update-shell
Update shell configuration for tool PATH.
uv tool update-shell
Virtual Environment Commands
uv venv
Create a virtual environment.
uv venv [OPTIONS] [PATH]
Options:
| Option | Description |
|---|---|
--python <VERSION> |
Python version |
--system-site-packages |
Allow access to system packages |
--seed |
Install seed packages (pip, setuptools) |
--relocatable |
Make environment relocatable |
--prompt <NAME> |
Custom prompt name |
Examples:
uv venv
uv venv .venv
uv venv --python 3.12 my-env
uv venv --seed # Include pip
pip Interface Commands
uv pip install
Install packages.
uv pip install [OPTIONS] <PACKAGES>...
Options:
| Option | Description |
|---|---|
-r, --requirement <FILE> |
Requirements file |
-e, --editable <PATH> |
Editable install |
-c, --constraint <FILE> |
Constraint file |
--index-url <URL> |
Package index |
--extra-index-url <URL> |
Additional index |
--no-deps |
Don't install dependencies |
--no-binary <PKG> |
Build from source |
--only-binary <PKG> |
Only use wheels |
--upgrade, -U |
Upgrade packages |
--reinstall |
Reinstall packages |
--system |
Use system Python |
--python <VERSION> |
Target Python |
Examples:
uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .
uv pip install --upgrade requests
uv pip uninstall
Uninstall packages.
uv pip uninstall [OPTIONS] <PACKAGES>...
uv pip compile
Compile requirements.
uv pip compile [OPTIONS] <SRC>...
Options:
| Option | Description |
|---|---|
-o, --output-file <FILE> |
Output file |
--upgrade |
Upgrade all packages |
--upgrade-package <PKG> |
Upgrade specific package |
--no-header |
Omit header comment |
--generate-hashes |
Include hashes |
--all-extras |
Include all extras |
Examples:
uv pip compile requirements.in -o requirements.txt
uv pip compile pyproject.toml -o requirements.txt
uv pip compile requirements.in --upgrade
uv pip sync
Sync environment with requirements.
uv pip sync [OPTIONS] <REQUIREMENTS>...
Examples:
uv pip sync requirements.txt
uv pip freeze
List installed packages.
uv pip freeze [OPTIONS]
uv pip list
List installed packages.
uv pip list [OPTIONS]
Options:
| Option | Description |
|---|---|
--editable |
Only editable packages |
--exclude-editable |
Exclude editable packages |
--outdated |
Show outdated packages |
--format <FORMAT> |
Output format (columns, freeze, json) |
uv pip show
Show package information.
uv pip show <PACKAGES>...
uv pip check
Verify installed packages have compatible dependencies.
uv pip check
Build and Publish Commands
uv build
Build distributions.
uv build [OPTIONS] [SRC]
Options:
| Option | Description |
|---|---|
--wheel |
Build only wheel |
--sdist |
Build only source distribution |
--out-dir, -o <DIR> |
Output directory |
--python <VERSION> |
Python version |
--no-build-isolation |
Disable build isolation |
Examples:
uv build
uv build --wheel
uv build -o dist/
uv publish
Publish distributions.
uv publish [OPTIONS] [DIST]...
Options:
| Option | Description |
|---|---|
--repository <URL> |
Repository URL |
--token <TOKEN> |
API token |
--username <USER> |
Username |
--password <PASS> |
Password |
--check-url <URL> |
Check if version exists |
Examples:
uv publish
uv publish dist/*
uv publish --token $PYPI_TOKEN
Cache Commands
uv cache clean
Clear cache.
uv cache clean [PACKAGES]...
uv cache prune
Remove outdated cache entries.
uv cache prune [OPTIONS]
Options:
| Option | Description |
|---|---|
--ci |
Aggressive pruning for CI |
uv cache dir
Show cache directory path.
uv cache dir
Authentication Commands
uv auth login
Authenticate with a service.
uv auth login [OPTIONS] <SERVICE>
Options:
| Option | Description |
|---|---|
-u, --username <USER> |
Username |
-t, --token |
Use API token |
--password <PASS> |
Password |
--keyring-provider <PROVIDER> |
Credential backend |
Examples:
uv auth login pypi
uv auth login pypi --token
uv auth login https://private.pypi.org
uv auth logout
Remove authentication.
uv auth logout [OPTIONS] <SERVICE>
uv auth token
Show authentication token.
uv auth token <SERVICE>
Global Options
Available for most commands:
| Option | Description |
|---|---|
-v, --verbose |
Verbose output |
-q, --quiet |
Quiet output |
--color <CHOICE> |
Color output (auto, always, never) |
--no-progress |
Hide progress bars |
--project <DIR> |
Project directory |
--directory <DIR> |
Working directory |
--config-file <FILE> |
Config file path |
--no-config |
Ignore config files |
--cache-dir <DIR> |
Cache directory |
--no-cache |
Disable caching |
--offline |
Disable network access |
--python <VERSION> |
Python version |
--managed-python |
Require uv-managed Python |
--no-managed-python |
Allow system Python |
--no-python-downloads |
Don't download Python |
-h, --help |
Show help |
Version Request Formats
uv accepts various Python version formats:
| Format | Example | Description |
|---|---|---|
| Version | 3.12, 3.12.5 |
Specific version |
| Range | >=3.11,<3.13 |
Version constraint |
| Variant | 3.13t, 3.13+freethreaded |
Free-threaded |
| Debug | 3.13d, 3.13+debug |
Debug build |
| Implementation | cpython, pypy |
Python implementation |
| Path | /usr/bin/python3 |
Executable path |
Environment Variables
See references/integrations.md for complete environment variable reference.
Key variables:
UV_CACHE_DIR- Cache directoryUV_PYTHON- Default Python versionUV_INDEX_URL/UV_DEFAULT_INDEX- Package indexUV_FROZEN- Use lockfile without updatingUV_LOCKED- Assert lockfile unchangedUV_LINK_MODE- Package linking modeUV_COMPILE_BYTECODE- Compile .pyc files