633 lines
16 KiB
Markdown
633 lines
16 KiB
Markdown
# uv CLI Reference
|
|
|
|
Complete command-line interface reference for uv (v0.9.5).
|
|
|
|
## Global Flags
|
|
|
|
Available across all commands:
|
|
|
|
```bash
|
|
--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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
uv tool upgrade [OPTIONS] [PACKAGE]
|
|
|
|
--all Upgrade all tools
|
|
```
|
|
|
|
### uv tool list
|
|
|
|
List installed tools.
|
|
|
|
```bash
|
|
uv tool list [OPTIONS]
|
|
|
|
--show-paths Display installation paths
|
|
```
|
|
|
|
### uv tool uninstall
|
|
|
|
Remove installed tool.
|
|
|
|
```bash
|
|
uv tool uninstall <PACKAGE>
|
|
```
|
|
|
|
## Python Management
|
|
|
|
### uv python install
|
|
|
|
Install Python versions.
|
|
|
|
```bash
|
|
uv python install [OPTIONS] <VERSIONS>...
|
|
|
|
--force Reinstall if present
|
|
--preview Allow preview versions
|
|
```
|
|
|
|
### uv python list
|
|
|
|
List Python versions.
|
|
|
|
```bash
|
|
uv python list [OPTIONS]
|
|
|
|
--all-versions Show all available versions
|
|
--only-installed Show only installed versions
|
|
```
|
|
|
|
### uv python pin
|
|
|
|
Pin Python version for project.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
uv python find <VERSION>
|
|
```
|
|
|
|
### uv python upgrade
|
|
|
|
Update Python installations.
|
|
|
|
```bash
|
|
uv python upgrade [OPTIONS] [VERSION]
|
|
|
|
--all Upgrade all installations
|
|
```
|
|
|
|
## pip Interface
|
|
|
|
### uv pip install
|
|
|
|
Install packages.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
uv pip show <PACKAGE>
|
|
|
|
--python <PYTHON> Target Python environment
|
|
--system Target system Python
|
|
```
|
|
|
|
### uv pip tree
|
|
|
|
Display dependency tree.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
uv pip check [OPTIONS]
|
|
|
|
--python <PYTHON> Target Python environment
|
|
--system Target system Python
|
|
```
|
|
|
|
## Virtual Environments
|
|
|
|
### uv venv
|
|
|
|
Create virtual environment.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
uv cache clean [OPTIONS] [PACKAGE]
|
|
|
|
--package <PACKAGE> Clean specific package only
|
|
```
|
|
|
|
### uv cache prune
|
|
|
|
Remove unreachable entries.
|
|
|
|
```bash
|
|
uv cache prune [OPTIONS]
|
|
|
|
--ci Optimize for CI (keep wheels, remove downloads)
|
|
```
|
|
|
|
### uv cache dir
|
|
|
|
Show cache directory path.
|
|
|
|
```bash
|
|
uv cache dir
|
|
```
|
|
|
|
## Self Management
|
|
|
|
### uv self update
|
|
|
|
Update uv itself.
|
|
|
|
```bash
|
|
uv self update [OPTIONS]
|
|
|
|
--version <VERSION> Update to specific version
|
|
```
|
|
|
|
### uv self version
|
|
|
|
Show uv version.
|
|
|
|
```bash
|
|
uv self version
|
|
uv --version # Equivalent
|
|
uv -V # Short form
|
|
```
|
|
|
|
## Utility Commands
|
|
|
|
### uv generate-shell-completion
|
|
|
|
Generate shell completions.
|
|
|
|
```bash
|
|
uv generate-shell-completion <SHELL>
|
|
|
|
# Shells: bash, zsh, fish, elvish, powershell
|
|
```
|
|
|
|
## Index and Resolution Flags
|
|
|
|
Control package index behavior:
|
|
|
|
```bash
|
|
--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:
|
|
|
|
```bash
|
|
--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:**
|
|
|
|
```bash
|
|
uv init myproject --lib
|
|
cd myproject
|
|
uv add requests pytest --dev
|
|
uv lock
|
|
uv sync
|
|
uv run pytest
|
|
```
|
|
|
|
**Create and run script:**
|
|
|
|
```bash
|
|
uv init --script analyze.py
|
|
uv add --script analyze.py pandas matplotlib
|
|
uv run analyze.py
|
|
```
|
|
|
|
**Install and use tools:**
|
|
|
|
```bash
|
|
uvx ruff check
|
|
uv tool install black
|
|
black myfile.py
|
|
```
|
|
|
|
**Python version management:**
|
|
|
|
```bash
|
|
uv python install 3.12
|
|
uv python pin 3.12
|
|
uv run --python 3.11 script.py
|
|
```
|
|
|
|
**pip interface:**
|
|
|
|
```bash
|
|
uv pip install flask
|
|
uv pip compile requirements.in -o requirements.txt
|
|
uv pip sync requirements.txt
|
|
```
|
|
|
|
**Build and publish:**
|
|
|
|
```bash
|
|
uv build
|
|
uv publish --token $PYPI_TOKEN
|
|
```
|