16 KiB
16 KiB
uv CLI Reference
Complete command-line interface reference for uv (v0.9.5).
Global Flags
Available across all commands:
--help, -h Display help
--verbose, -v Verbose logging (repeat for more: -vv, -vvv)
--quiet, -q Suppress output
--color <WHEN> Color output (auto/always/never)
--no-progress Hide progress indicators
--cache-dir <DIR> Cache directory
--no-cache Disable caching
--offline Disable network access
--python <VERSION> Python interpreter/version
--directory <PATH> Working directory
--config-file <PATH> Custom config file
--no-config Ignore config files
--preview Enable preview features
Project Commands
uv init
Create new project or script.
uv init [OPTIONS] [PATH]
--lib, --library Create library (implies --package)
--app, --application Create application (default)
--script Create PEP 723 script
--package Distributable package with src/
--no-package Non-package (virtual) project
--bare Minimal configuration only
--build-backend <BACKEND> Build system (hatchling/setuptools/uv_build)
--python <VERSION> Python version requirement
--vcs <VCS> Version control (git/none)
--python-pin Create .python-version
uv add
Add dependencies to project.
uv add [OPTIONS] <PACKAGES>...
--dev Add to dev dependencies
--group <GROUP> Add to dependency group
--optional <EXTRA> Add to optional dependencies
--editable, -e Editable/development mode
--frozen Skip lockfile updates
--locked Assert lockfile unchanged
--no-sync Skip environment sync
--bounds <TYPE> Version constraint (lowest/compatible/exact)
--branch <BRANCH> Git branch
--tag <TAG> Git tag
--rev <REV> Git revision
--raw-sources Raw source specifiers
uv remove
Remove dependencies.
uv remove [OPTIONS] <PACKAGES>...
--dev Remove from dev dependencies
--group <GROUP> Remove from dependency group
--optional <EXTRA> Remove from optional dependencies
--frozen Skip lockfile updates
--locked Assert lockfile unchanged
uv sync
Synchronize project environment with lockfile.
uv sync [OPTIONS]
--extra <EXTRA>, -E Include optional dependencies
--all-extras Include all optional dependencies
--no-dev Exclude dev dependencies
--only-dev Only dev dependencies
--group <GROUP> Include dependency group
--only-group <GROUP> Only specified group
--no-install-project Skip installing project itself
--frozen Use existing lockfile
--locked Assert lockfile unchanged
--inexact Allow non-exact versions
--python <VERSION> Target Python version
uv lock
Update project lockfile.
uv lock [OPTIONS]
--frozen Don't update lockfile
--locked Assert lockfile unchanged
--upgrade, -U Allow package upgrades
--upgrade-package <PKG>, -P Upgrade specific packages
--dry-run Show changes without writing
uv run
Execute commands in project environment.
uv run [OPTIONS] <COMMAND> [ARGS]...
--python <VERSION> Python version
--module, -m Run as module
--script, -s Treat as PEP 723 script
--with <PKG>, -w Include temporary packages
--isolated Fresh isolated environment
--frozen Skip lockfile updates
--locked Assert lockfile unchanged
--no-sync Skip environment sync
--no-project Don't load project environment
--no-dev Exclude dev dependencies
--extra <EXTRA> Include optional dependencies
--all-extras Include all optional dependencies
--package <PKG> Run for specific workspace package
--env-file <FILE> Load environment variables
uv tree
Display dependency tree.
uv tree [OPTIONS]
--depth <DEPTH> Maximum display depth
--prune <PKG> Prune packages from tree
--package <PKG> Show tree for specific package
--invert Show reverse dependencies
--no-dedupe Show all occurrences
uv export
Export dependencies to various formats.
uv export [OPTIONS]
--format <FORMAT> Output format (requirements-txt/pylock)
-o, --output-file <FILE> Output file path
--extra <EXTRA> Include optional dependencies
--all-extras Include all optional dependencies
--no-dev Exclude dev dependencies
--frozen Use existing lockfile
Tool Management
uv tool run (alias: uvx)
Execute tool without persistent installation.
uvx [OPTIONS] <COMMAND> [ARGS]...
uv tool run [OPTIONS] <COMMAND> [ARGS]...
--from <PACKAGE> Source package
--with <PACKAGE> Include additional packages
--python <VERSION> Python version
--isolated Fresh environment
uv tool install
Install tool persistently.
uv tool install [OPTIONS] <PACKAGE>
--from <PACKAGE> Install from specific package
--with <PACKAGE> Include additional packages
--python <VERSION> Python version
--force Overwrite existing
--editable, -e Editable mode
uv tool upgrade
Update installed tool.
uv tool upgrade [OPTIONS] [PACKAGE]
--all Upgrade all tools
uv tool list
List installed tools.
uv tool list [OPTIONS]
--show-paths Display installation paths
uv tool uninstall
Remove installed tool.
uv tool uninstall <PACKAGE>
Python Management
uv python install
Install Python versions.
uv python install [OPTIONS] <VERSIONS>...
--force Reinstall if present
--preview Allow preview versions
uv python list
List Python versions.
uv python list [OPTIONS]
--all-versions Show all available versions
--only-installed Show only installed versions
uv python pin
Pin Python version for project.
uv python pin [OPTIONS] <VERSION>
--global Pin globally for user
--rm Remove pin
--python-preference <PREF> Preference (only-managed/managed/system/only-system)
uv python find
Locate Python interpreter.
uv python find <VERSION>
uv python upgrade
Update Python installations.
uv python upgrade [OPTIONS] [VERSION]
--all Upgrade all installations
pip Interface
uv pip install
Install packages.
uv pip install [OPTIONS] <PACKAGES>...
--requirement <FILE>, -r Install from requirements
--editable <PATH>, -e Editable mode
--constraint <FILE>, -c Apply constraints
--override <FILE> Apply overrides
--extra <EXTRA> Install optional dependencies
--all-extras Install all optional dependencies
--no-deps Don't install dependencies
--python <PYTHON> Target Python environment
--system Install into system Python
--break-system-packages Allow system modifications
--target <DIR> Install to directory
--upgrade, -U Upgrade packages
--upgrade-package <PKG>, -P Upgrade specific packages
--force-reinstall Reinstall even if satisfied
--no-build Don't build from source
--no-binary <PKG> Don't use wheels
--only-binary <PKG> Only use wheels
--dry-run Show changes without installing
uv pip compile
Generate requirements file.
uv pip compile [OPTIONS] <INPUT_FILES>...
-o, --output-file <FILE> Output file
--extra <EXTRA> Include optional dependencies
--all-extras Include all optional dependencies
--constraint <FILE>, -c Apply constraints
--override <FILE> Apply overrides
--python <VERSION> Target Python version
--python-platform <PLATFORM> Target platform
--python-version <VERSION> Python version constraint
--universal Cross-platform requirements
--no-strip-markers Preserve environment markers
--resolution <STRATEGY> Resolution strategy (highest/lowest/lowest-direct)
--prerelease <MODE> Pre-release handling (allow/disallow/if-necessary/if-necessary-or-explicit)
--upgrade, -U Allow upgrades
--upgrade-package <PKG>, -P Upgrade specific packages
--generate-hashes Include package hashes
--annotation-style <STYLE> Annotation format (line/split)
uv pip sync
Install from requirements file.
uv pip sync [OPTIONS] <FILE>
--python <PYTHON> Target Python environment
--system Install into system Python
--break-system-packages Allow system modifications
--target <DIR> Install to directory
--no-build Don't build from source
--dry-run Show changes without installing
--reinstall Reinstall all packages
--link-mode <MODE> Installation link mode (clone/copy/hardlink/symlink)
--compile-bytecode Compile to bytecode
--require-hashes Require package hashes
uv pip uninstall
Remove packages.
uv pip uninstall [OPTIONS] <PACKAGES>...
--requirement <FILE>, -r Uninstall from requirements
--python <PYTHON> Target Python environment
--system Uninstall from system Python
uv pip freeze
List installed packages.
uv pip freeze [OPTIONS]
--exclude-editable Exclude editable packages
--strict Fail on missing dependencies
--python <PYTHON> Target Python environment
uv pip list
List installed packages with formatting.
uv pip list [OPTIONS]
--editable, -e Show only editable packages
--exclude-editable Exclude editable packages
--format <FORMAT> Output format (columns/freeze/json)
--python <PYTHON> Target Python environment
--system Target system Python
uv pip show
Display package information.
uv pip show <PACKAGE>
--python <PYTHON> Target Python environment
--system Target system Python
uv pip tree
Display dependency tree.
uv pip tree [OPTIONS]
--depth <DEPTH> Maximum display depth
--prune <PKG> Prune packages
--package <PKG> Show tree for specific package
--invert Show reverse dependencies
--python <PYTHON> Target Python environment
--no-dedupe Show all occurrences
uv pip check
Verify dependencies.
uv pip check [OPTIONS]
--python <PYTHON> Target Python environment
--system Target system Python
Virtual Environments
uv venv
Create virtual environment.
uv venv [OPTIONS] [PATH]
--python <VERSION> Python version
--seed Install seed packages (pip, setuptools, wheel)
--prompt <PROMPT> Custom environment prompt
--system-site-packages Access to system packages
--relocatable Relocatable environment
--allow-existing Allow existing directory
--no-project Don't detect project
Build and Publish
uv build
Build Python packages.
uv build [OPTIONS] [SRC]
--sdist Build source distribution only
--wheel Build wheel only
--out-dir <DIR> Output directory (default: dist/)
--package <PACKAGE> Build specific workspace package
--no-build-isolation Disable build isolation
--build-constraint <FILE> Apply build constraints
--config-setting <KEY=VALUE> Pass settings to build backend
uv publish
Upload distributions to package indexes.
uv publish [OPTIONS] [FILES]...
--username <USER>, -u Registry username
--password <PASS>, -p Registry password
--token <TOKEN>, -t Authentication token
--publish-url <URL> Registry URL (default: PyPI)
--index <NAME> Named index from config
--keyring-provider <PROVIDER> Keyring authentication
--trusted-publishing <MODE> OIDC trusted publishing (always/if-available/never)
--check-url <URL> Verify package existence URL
--build Build packages before publishing
--no-build Publish existing distributions
Cache Management
uv cache clean
Clear cache.
uv cache clean [OPTIONS] [PACKAGE]
--package <PACKAGE> Clean specific package only
uv cache prune
Remove unreachable entries.
uv cache prune [OPTIONS]
--ci Optimize for CI (keep wheels, remove downloads)
uv cache dir
Show cache directory path.
uv cache dir
Self Management
uv self update
Update uv itself.
uv self update [OPTIONS]
--version <VERSION> Update to specific version
uv self version
Show uv version.
uv self version
uv --version # Equivalent
uv -V # Short form
Utility Commands
uv generate-shell-completion
Generate shell completions.
uv generate-shell-completion <SHELL>
# Shells: bash, zsh, fish, elvish, powershell
Index and Resolution Flags
Control package index behavior:
--index <NAME>=<URL> Named package index
--default-index <URL> Primary index
--extra-index-url <URL> Supplementary index
--find-links <PATH_OR_URL> Find-links location
--no-index Ignore all indexes
--index-strategy <STRATEGY> Resolution strategy (first-index/unsafe-first-match/unsafe-best-match)
--resolution <STRATEGY> Version selection (highest/lowest/lowest-direct)
--prerelease <MODE> Pre-release handling
--exclude-newer <TIMESTAMP> Exclude packages newer than timestamp
--no-sources Ignore [tool.uv.sources]
Build Flags
Control build and installation:
--no-build Don't build from source
--no-binary <PKG> Don't use wheels (use :all: for all)
--only-binary <PKG> Only use wheels (use :all: for all)
--no-build-isolation Disable build isolation
--no-build-isolation-package <PKG> Disable for specific packages
--build-constraint <FILE> Build dependency constraints
--config-setting <KEY=VALUE> PEP 517 build backend settings
--link-mode <MODE> Installation method (clone/copy/hardlink/symlink)
--compile-bytecode Compile to bytecode
--reinstall Reinstall all packages
--reinstall-package <PKG> Reinstall specific packages
--require-hashes Require package hashes
Examples
Initialize and manage project:
uv init myproject --lib
cd myproject
uv add requests pytest --dev
uv lock
uv sync
uv run pytest
Create and run script:
uv init --script analyze.py
uv add --script analyze.py pandas matplotlib
uv run analyze.py
Install and use tools:
uvx ruff check
uv tool install black
black myfile.py
Python version management:
uv python install 3.12
uv python pin 3.12
uv run --python 3.11 script.py
pip interface:
uv pip install flask
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
Build and publish:
uv build
uv publish --token $PYPI_TOKEN