Skip to main content

​
Overview

uv is an extremely fast Python package and project manager with a comprehensive command-line interface. The CLI is organized into logical command categories for managing projects, Python installations, tools, packages, and more. 
uv [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS] [ARGUMENTS]

​
Command Categories

uv organizes commands into several categories based on their purpose:

Project Commands

Manage Python projects with dependencies and virtual environments

Python Management

Install and manage Python versions

Tool Commands

Run and install command-line tools from Python packages

Pip Interface

Drop-in pip-compatible commands for package management

Build & Publish

Build distributions and publish packages to indexes

Environment

Create and manage virtual environments

Cache & Maintenance

Manage cache and update uv itself

Authentication

Configure authentication for package indexes

​
Project Commands

Manage complete Python projects with lockfiles, dependencies, and environments:
  • uv init - Create a new project
  • uv add - Add dependencies to a project
  • uv remove - Remove dependencies from a project
  • uv sync - Sync project environment with lockfile
  • uv lock - Update the project lockfile
  • uv run - Run a command in the project environment
  • uv tree - Display project dependency tree
  • uv export - Export lockfile to alternate formats
  • uv version - Read or update project version
  • uv build - Build source distributions and wheels
  • uv format - Format Python code using Ruff

​
Python Management

Install and manage Python interpreters:
  • uv python install - Install Python versions
  • uv python list - List available and installed Python versions
  • uv python find - Find a Python interpreter
  • uv python pin - Pin a Python version for a project
  • uv python uninstall - Uninstall Python versions

​
Tool Commands

Run and install isolated command-line tools:
  • uv tool run (or uvx) - Run a tool in an ephemeral environment
  • uv tool install - Install a tool globally
  • uv tool list - List installed tools
  • uv tool uninstall - Uninstall a tool
  • uv tool update-shell - Update shell completions

​
Pip Interface

Drop-in replacement for pip and pip-tools commands:
  • uv pip install - Install packages
  • uv pip compile - Compile requirements files
  • uv pip sync - Sync environment with requirements
  • uv pip uninstall - Uninstall packages
  • uv pip freeze - List installed packages (requirements format)
  • uv pip list - List installed packages (table format)
  • uv pip show - Show package information
  • uv pip tree - Display dependency tree
  • uv pip check - Verify package dependencies

​
Build & Publish

Build and distribute Python packages:
  • uv build - Build source distributions and wheels
  • uv publish - Upload distributions to an index

​
Environment

Manage virtual environments:
  • uv venv - Create a virtual environment

​
Cache & Maintenance

Manage uv’s cache and update the tool itself:
  • uv cache clean - Remove cache entries for specific packages
  • uv cache prune - Remove all unreachable cache objects
  • uv cache dir - Show the cache directory path
  • uv cache size - Show total cache size
  • uv self update - Update uv to the latest version

​
Authentication

Manage authentication for package indexes:
  • uv auth - Configure credentials for authenticated indexes

​
Global Options

Global options can be used with any uv command and must appear before the command name.

​
Python Options

Control Python interpreter discovery and installation:
​
--python
string
The Python interpreter to use for the operation.Supports version numbers (3.12), version specifiers (>=3.8), implementation names (cpython), executable names (python3), or paths (/usr/bin/python3).See uv help python for complete details on Python discovery.Environment variable: UV_PYTHON
​
--managed-python
boolean
Require use of uv-managed Python versions.By default, uv prefers managed Python but will fall back to system Python. This option disables system Python fallback.Environment variable: UV_MANAGED_PYTHON
​
--no-managed-python
boolean
Disable use of uv-managed Python versions and search only system Python.Environment variable: UV_NO_MANAGED_PYTHON
​
--no-python-downloads
boolean
Disable automatic Python downloads when required versions are not found.Environment variable: UV_PYTHON_DOWNLOADS=never

​
Output Control

Adjust verbosity and formatting:
​
--quiet, -q
flag
Use quiet output. Suppress non-error messages.Repeat (-qq) for silent mode with no stdout output.
​
--verbose, -v
flag
Use verbose output. Show additional details.For fine-grained logging control, use the RUST_LOG environment variable.
​
--color
auto | always | never
Control color output.
  • auto - Detect terminal support (default)
  • always - Force color output
  • never - Disable color output
Default: auto
​
--no-progress
boolean
Hide progress indicators like spinners and progress bars.Environment variable: UV_NO_PROGRESS

​
Network Options

Configure network behavior and security:
​
--offline
boolean
Disable network access.When enabled, uv will only use locally cached data and locally available files.Environment variable: UV_OFFLINE
​
--native-tls
boolean
Use the platform’s native TLS certificate store instead of bundled webpki-roots.Useful for corporate environments with custom root certificates.Environment variable: UV_NATIVE_TLS
​
--allow-insecure-host
string
Allow insecure connections to the specified host.Accepts hostname, host:port, or URL. Can be provided multiple times.
Only use on trusted networks. This bypasses SSL verification and exposes you to man-in-the-middle attacks.
Environment variable: UV_INSECURE_HOST

​
Cache Options

Control cache behavior and location:
​
--no-cache, -n
boolean
Avoid using the cache. Uses a temporary directory instead.Environment variable: UV_NO_CACHE
​
--cache-dir
path
Path to the cache directory.Default locations:
  • macOS/Linux: $XDG_CACHE_HOME/uv or $HOME/.cache/uv
  • Windows: %LOCALAPPDATA%\uv\cache
Use uv cache dir to view the current cache location.Environment variable: UV_CACHE_DIR

​
Configuration

Control configuration file discovery and location:
​
--config-file
path
Path to a uv.toml configuration file.Configuration in pyproject.toml is not allowed when this option is used.Environment variable: UV_CONFIG_FILE
​
--no-config
boolean
Avoid discovering configuration files (pyproject.toml, uv.toml).Configuration files are normally discovered in the current directory, parent directories, or user configuration directories.Environment variable: UV_NO_CONFIG

​
Directory Options

Control working directory and project discovery:
​
--directory
path
Change to the specified directory before running the command.All relative paths are resolved from this directory.Environment variable: UV_WORKING_DIR
​
--project
path
Discover the project in the specified directory.Project files (pyproject.toml, uv.toml, .python-version) and the virtual environment (.venv) are discovered from the project root. Other arguments remain relative to the current working directory.This setting has no effect when using the uv pip interface.Environment variable: UV_PROJECT

​
Other Options

​
--help, -h
flag
Display help information for the command.
​
--version, -V
flag
Display the uv version.

​
Usage Patterns

​
Combining Global Options

Global options must appear before the command name: 
# Correct
uv --quiet --offline pip install requests

# Incorrect - options after command are command-specific
uv pip install --quiet requests

​
Using Environment Variables

Most options have corresponding environment variables: 
# Using flags
uv --offline --no-cache pip install requests

# Using environment variables
export UV_OFFLINE=1
export UV_NO_CACHE=1
uv pip install requests

​
Configuration Priority

Settings are applied in the following priority order (highest to lowest):
  1. Command-line arguments
  2. Environment variables
  3. Project-level configuration (pyproject.toml or uv.toml)
  4. User-level configuration (~/.config/uv/uv.toml)
  5. Default values

​
Getting Help

Display help for any command or subcommand: 
# Top-level help
uv --help
uv help

# Command help
uv pip --help
uv help pip

# Subcommand help
uv pip install --help
uv help pip install
Use uv help <command> instead of uv <command> --help to view help in a pager for easier navigation.

​
Help System

uv provides comprehensive help documentation through the CLI:

​
Built-in Help

Access help directly from the command line: 
# General help
uv help

# Command-specific help
uv help run
uv help pip install

# Disable pager
uv help --no-pager sync

​
Python Discovery Help

Get detailed information about Python interpreter discovery: 
uv help python
This displays:
  • Python version request formats
  • Discovery rules and priority
  • Supported implementations (CPython, PyPy, GraalPy)
  • System-specific behavior (PATH, registry on Windows)

​
Command Aliases

Some commands have convenient aliases:
  • uvx - Alias for uv tool run
  • uv venv - Also accepts virtualenv and v
  • uv pip list - Also accepts ls

​
Shell Completion

Generate shell completion scripts: 
# Bash
uv generate-shell-completion bash > ~/.local/share/bash-completion/completions/uv

# Zsh
uv generate-shell-completion zsh > ~/.zfunc/_uv

# Fish
uv generate-shell-completion fish > ~/.config/fish/completions/uv.fish

# PowerShell
uv generate-shell-completion powershell > ~\Documents\PowerShell\Scripts\uv.ps1
Or use uv tool update-shell to automatically configure completions for installed tools.

​
Exit Codes

uv uses standard exit codes:
  • 0 - Success
  • 1 - General error (invalid arguments, command failed, etc.)
  • 2 - Package not found or resolution failed

​
Next Steps

Project Commands

Learn about project management commands

Python Management

Explore Python installation and management

Tool Commands

Discover tool isolation and execution

Pip Interface

Use familiar pip-compatible commands

Build docs developers (and LLMs) love

Get started for freeTalk to us