> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference Overview

> Complete reference for the uv command-line interface, including global options, command categories, and usage patterns

## 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.

```bash theme={null}
uv [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS] [ARGUMENTS]
```

## Command Categories

uv organizes commands into several categories based on their purpose:

<CardGroup cols={2}>
  <Card title="Project Commands" icon="folder" href="#project-commands">
    Manage Python projects with dependencies and virtual environments
  </Card>

  <Card title="Python Management" icon="python" href="#python-management">
    Install and manage Python versions
  </Card>

  <Card title="Tool Commands" icon="wrench" href="#tool-commands">
    Run and install command-line tools from Python packages
  </Card>

  <Card title="Pip Interface" icon="box" href="#pip-interface">
    Drop-in pip-compatible commands for package management
  </Card>

  <Card title="Build & Publish" icon="upload" href="#build-publish">
    Build distributions and publish packages to indexes
  </Card>

  <Card title="Environment" icon="layer-group" href="#environment">
    Create and manage virtual environments
  </Card>

  <Card title="Cache & Maintenance" icon="database" href="#cache-maintenance">
    Manage cache and update uv itself
  </Card>

  <Card title="Authentication" icon="key" href="#authentication">
    Configure authentication for package indexes
  </Card>
</CardGroup>

### 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:

<ParamField path="--python" type="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`
</ParamField>

<ParamField path="--managed-python" type="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`
</ParamField>

<ParamField path="--no-managed-python" type="boolean">
  Disable use of uv-managed Python versions and search only system Python.

  **Environment variable:** `UV_NO_MANAGED_PYTHON`
</ParamField>

<ParamField path="--no-python-downloads" type="boolean">
  Disable automatic Python downloads when required versions are not found.

  **Environment variable:** `UV_PYTHON_DOWNLOADS=never`
</ParamField>

### Output Control

Adjust verbosity and formatting:

<ParamField path="--quiet, -q" type="flag">
  Use quiet output. Suppress non-error messages.

  Repeat (`-qq`) for silent mode with no stdout output.
</ParamField>

<ParamField path="--verbose, -v" type="flag">
  Use verbose output. Show additional details.

  For fine-grained logging control, use the `RUST_LOG` environment variable.
</ParamField>

<ParamField path="--color" type="auto | always | never">
  Control color output.

  * `auto` - Detect terminal support (default)
  * `always` - Force color output
  * `never` - Disable color output

  **Default:** `auto`
</ParamField>

<ParamField path="--no-progress" type="boolean">
  Hide progress indicators like spinners and progress bars.

  **Environment variable:** `UV_NO_PROGRESS`
</ParamField>

### Network Options

Configure network behavior and security:

<ParamField path="--offline" type="boolean">
  Disable network access.

  When enabled, uv will only use locally cached data and locally available files.

  **Environment variable:** `UV_OFFLINE`
</ParamField>

<ParamField path="--native-tls" type="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`
</ParamField>

<ParamField path="--allow-insecure-host" type="string">
  Allow insecure connections to the specified host.

  Accepts hostname, host:port, or URL. Can be provided multiple times.

  <Warning>
    Only use on trusted networks. This bypasses SSL verification and exposes you to man-in-the-middle attacks.
  </Warning>

  **Environment variable:** `UV_INSECURE_HOST`
</ParamField>

### Cache Options

Control cache behavior and location:

<ParamField path="--no-cache, -n" type="boolean">
  Avoid using the cache. Uses a temporary directory instead.

  **Environment variable:** `UV_NO_CACHE`
</ParamField>

<ParamField path="--cache-dir" type="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`
</ParamField>

### Configuration

Control configuration file discovery and location:

<ParamField path="--config-file" type="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`
</ParamField>

<ParamField path="--no-config" type="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`
</ParamField>

### Directory Options

Control working directory and project discovery:

<ParamField path="--directory" type="path">
  Change to the specified directory before running the command.

  All relative paths are resolved from this directory.

  **Environment variable:** `UV_WORKING_DIR`
</ParamField>

<ParamField path="--project" type="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`
</ParamField>

### Other Options

<ParamField path="--help, -h" type="flag">
  Display help information for the command.
</ParamField>

<ParamField path="--version, -V" type="flag">
  Display the uv version.
</ParamField>

## Usage Patterns

### Combining Global Options

Global options must appear before the command name:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Tip>
  Use `uv help <command>` instead of `uv <command> --help` to view help in a pager for easier navigation.
</Tip>

## Help System

uv provides comprehensive help documentation through the CLI:

### Built-in Help

Access help directly from the command line:

```bash theme={null}
# 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:

```bash theme={null}
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 theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Project Commands" icon="folder" href="/cli/init">
    Learn about project management commands
  </Card>

  <Card title="Python Management" icon="python" href="/cli/python-install">
    Explore Python installation and management
  </Card>

  <Card title="Tool Commands" icon="wrench" href="/cli/tool-run">
    Discover tool isolation and execution
  </Card>

  <Card title="Pip Interface" icon="box" href="/cli/pip-install">
    Use familiar pip-compatible commands
  </Card>
</CardGroup>