# uv — User Guide

## 1. Quick Start

uv is an extremely fast Python package and project manager, written in Rust. It replaces `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more — in a single, self-contained binary that installs in seconds.

**Key features:**

- 10–100x faster than pip for installs and resolution
- Manages Python versions, virtual environments, projects, tools, and scripts
- Provides both a pip-compatible CLI and a first-class project interface with lockfiles
- Supports workspaces, dependency groups, and inline script metadata
- Publishes packages to PyPI with trusted publishing support
- Audits dependencies for known vulnerabilities
- Works on Linux, macOS, and Windows (x86_64, aarch64, arm, and more)
- Ships as a single static binary with no Python dependency

**Prerequisites:** A terminal. uv can install Python for you — no prior Python installation required.

**Install and run in 30 seconds:**

=== "macOS / Linux"
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

=== "Windows"
    ```powershell
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```

=== "pip"
    ```bash
    pip install uv
    ```

```bash
uv init my-project && cd my-project
uv add requests
uv run python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"
```

```text
Resolved 5 packages in 120ms
Installed 5 packages in 45ms
 + certifi==2024.8.30
 + charset-normalizer==3.3.2
 + idna==3.10
 + requests==2.32.3
 + urllib3==2.2.3
{'origin': '203.0.113.42'}
```

> [!TIP]
> Use `uvx` (alias for `uv tool run`) to run CLI tools without installing them: `uvx ruff check .`

**What to try next:**

- Install Python: `uv python install 3.12`
- Run a script: `uv run script.py`
- Add dev dependencies: `uv add --group dev pytest`
- See the Configuration section for `pyproject.toml` and `uv.toml` settings

## 2. Installation

### System Requirements

| Requirement | Details |
|---|---|
| OS | Linux (glibc ≥2.17), macOS (x86_64, aarch64), Windows 10+ |
| Architecture | x86_64, aarch64, armv7, i686, powerpc64le, riscv64, s390x |
| Disk space | ~30 MB for the binary |
| Python | **Not required** — uv can download and manage Python itself |

### Installation Methods

=== "Standalone Installer (Recommended)"
    ```bash
    # macOS / Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    ```powershell
    # Windows
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```

=== "Homebrew"
    ```bash
    brew install uv
    ```

=== "pip / pipx"
    ```bash
    pip install uv
    # or
    pipx install uv
    ```

=== "Cargo"
    ```bash
    cargo install --git https://github.com/astral-sh/uv uv
    ```

=== "Docker"
    ```dockerfile
    FROM ghcr.io/astral-sh/uv:latest AS uv
    COPY --from=uv /uv /usr/local/bin/uv
    ```

=== "Conda"
    ```bash
    conda install -c conda-forge uv
    ```

> [!IMPORTANT]
> The standalone installer places `uv` in `~/.local/bin` (Unix) or `%USERPROFILE%\.local\bin` (Windows). Ensure this directory is on your `PATH`.

### Post-Install Verification

```bash
uv --version
```

```text
uv 0.11.7
```

```bash
uv python list
```

```text
cpython-3.13.3-linux-x86_64-gnu    <download available>
cpython-3.12.10-linux-x86_64-gnu   <download available>
cpython-3.11.12-linux-x86_64-gnu   /usr/bin/python3.11
...
```

### Self-Update

```bash
uv self update
```

> [!TIP]
> Pin a specific version: `uv self update 0.11.7`

### Shell Completion

```bash
# 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 > _uv.ps1
```

### Install Troubleshooting

### Error: `command not found: uv`

**Cause:** The install directory is not on your `PATH`.

**Solution:**
1. Add `~/.local/bin` to your shell profile:
   ```bash
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   ```
2. On Windows, add `%USERPROFILE%\.local\bin` to your system PATH.

**Prevention:** The standalone installer prints the required PATH entry — follow its instructions.

### Error: TLS/SSL certificate errors

**Cause:** Corporate proxy or custom CA certificates.

**Solution:**
```bash
uv --system-certs pip install requests
```

Or set permanently:
```bash
export UV_SYSTEM_CERTS=true
```

**Prevention:** Set `system-certs = true` in your `uv.toml`.

### Error: `uv self update` fails on managed installs

**Cause:** uv was installed via a package manager (Homebrew, pip, etc.).

**Solution:** Update via the same package manager that installed it:
```bash
brew upgrade uv    # Homebrew
pip install -U uv  # pip
```

**Prevention:** Use the standalone installer for self-update support.

## 3. Configuration

uv reads settings from multiple sources, in order of precedence:

1. **CLI flags** (highest priority)
2. **Environment variables** (`UV_*`)
3. **Project config** — `[tool.uv]` in `pyproject.toml` or `uv.toml` in the project root
4. **User config** — `~/.config/uv/uv.toml` (Linux/macOS) or `%APPDATA%\uv\uv.toml` (Windows)
5. **System config** — `/etc/xdg/uv/uv.toml` or `/etc/uv/uv.toml` (Linux), `%SYSTEMDRIVE%\ProgramData\uv\uv.toml` (Windows)

### Minimal `uv.toml` Example

```toml
# ~/.config/uv/uv.toml — user-level defaults
python-preference = "managed-only"
compile-bytecode = true
concurrent-downloads = 16

[pip]
index-url = "https://pypi.org/simple"
```

### Common Settings

| Setting | Type | Default | Description |
|---|---|---|---|
| `python-preference` | string | `"managed"` | Prefer managed or system Python (`managed`, `system`, `managed-only`, `system-only`) |
| `python-downloads` | string | `"automatic"` | Whether to download Python (`automatic`, `manual`, `never`) |
| `compile-bytecode` | bool | `false` | Pre-compile `.py` → `.pyc` after install |
| `link-mode` | string | platform | How to link from cache (`clone`, `hardlink`, `copy`, `symlink`) |
| `concurrent-downloads` | int | auto | Max concurrent package downloads |
| `concurrent-builds` | int | CPU count | Max concurrent source builds |
| `concurrent-installs` | int | CPU count | Max concurrent installs |
| `cache-dir` | string | platform | Custom cache directory |
| `no-cache` | bool | `false` | Disable all caching |
| `preview` | bool | `false` | Enable preview features |
| `offline` | bool | `false` | Disable network access |
| `system-certs` | bool | `false` | Use platform TLS certificates |

### Common Environment Variables

| Variable | Description |
|---|---|
| `UV_CACHE_DIR` | Override cache directory |
| `UV_NO_CACHE` | Disable cache |
| `UV_TOOL_DIR` | Override tool installation directory |
| `UV_PYTHON_INSTALL_DIR` | Override managed Python installation directory |
| `UV_WORKING_DIR` | Override working directory |
| `UV_PROJECT` | Path to project directory |
| `UV_NO_CONFIG` | Ignore all configuration files |
| `UV_PREVIEW` | Enable preview features |
| `UV_OFFLINE` | Disable network access |
| `UV_NO_PROGRESS` | Disable progress bars |
| `UV_SYSTEM_CERTS` | Use platform TLS certificates |
| `UV_MANAGED_PYTHON` | Prefer managed Python |
| `UV_NO_SYNC` | Skip auto-sync before `uv run` |
| `UV_FROZEN` | Run without updating the lockfile |
| `UV_LOCKED` | Assert lockfile is up-to-date |

> [!NOTE]
> See the Admin Guide for the full configuration reference, including all `[tool.uv]` settings, index configuration, and resolver options.

## 4. Core Usage

### 4.1 Project Management

#### Initialize a Project

```bash
uv init my-project
cd my-project
```

```text
Initialized project `my-project` at `./my-project`
```

This creates a `pyproject.toml`, `.python-version`, `README.md`, and a `src/my_project/__init__.py` starter.

```bash
# Initialize as a library (with src layout)
uv init --lib my-lib

# Initialize as an application (flat layout)
uv init --app my-app

# Initialize in the current directory
uv init
```

#### Add Dependencies

```bash
uv add requests
uv add "flask>=3.0"
uv add --group dev pytest ruff mypy
uv add --optional plotting matplotlib
```

> [!TIP]
> Use `uv add --frozen` to add a dependency without resolving — useful for quickly editing `pyproject.toml` when you plan to lock later.

#### Remove Dependencies

```bash
uv remove requests
uv remove --group dev mypy
```

#### Lock Dependencies

```bash
uv lock
```

```text
Resolved 42 packages in 1.2s
```

This produces a `uv.lock` file — a cross-platform lockfile that pins every transitive dependency.

```bash
# Check if lockfile is current without updating
uv lock --check

# Upgrade all packages
uv lock --upgrade

# Upgrade a specific package
uv lock --upgrade-package requests
```

#### Sync Environment

```bash
uv sync
```

```text
Resolved 42 packages in 5ms
Installed 42 packages in 230ms
```

Syncs the virtual environment to match the lockfile. Creates the venv if it doesn't exist.

```bash
# Sync without dev dependencies
uv sync --no-dev

# Sync with specific extras
uv sync --extra plotting

# Sync with specific groups
uv sync --group dev --group docs
```

> [!WARNING]
> `uv sync` removes packages not in the lockfile. If you installed packages manually with `uv pip install`, they will be removed.

#### Run Commands

```bash
uv run python app.py
uv run pytest
uv run -- python -m my_module --arg value
```

`uv run` automatically syncs the environment before running. Use `--no-sync` or set `UV_NO_SYNC=1` to skip.

```bash
# Run with extra dependencies (not added to project)
uv run --with httpx python -c "import httpx; print(httpx.get('https://httpbin.org/ip').text)"

# Run a specific script
uv run script.py
```

#### Show Dependency Tree

```bash
uv tree
```

```text
my-project v0.1.0
├── requests v2.32.3
│   ├── certifi v2024.8.30
│   ├── charset-normalizer v3.3.2
│   ├── idna v3.10
│   └── urllib3 v2.2.3
└── flask v3.0.3
    ├── blinker v1.8.2
    ├── click v8.1.7
    ├── itsdangerous v2.2.0
    ├── jinja2 v3.1.4
    │   └── markupsafe v2.1.5
    └── werkzeug v3.0.4
        └── markupsafe v2.1.5
```

#### View / Set Version

```bash
# Display current version
uv version

# Set a specific version
uv version 1.2.3

# Bump version
uv version --bump minor
```

#### Export Lockfile

```bash
# Export to requirements.txt
uv export --format requirements-txt > requirements.txt

# Export without hashes
uv export --format requirements-txt --no-hashes > requirements.txt
```

### 4.2 Running Scripts

uv can run standalone Python scripts, including scripts with inline dependency metadata (PEP 723):

```python
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

import requests
print(requests.get("https://httpbin.org/ip").json())
```

```bash
uv run script.py
```

uv automatically creates a temporary environment with the declared dependencies.

### 4.3 Python Version Management

```bash
# Install a specific Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# List available and installed versions
uv python list

# Find a specific version
uv python find 3.12

# Pin project Python version
uv python pin 3.12

# Uninstall a managed Python
uv python uninstall 3.11
```

> [!NOTE]
> uv downloads Python from the `python-build-standalone` project by Astral. Set `UV_PYTHON_INSTALL_MIRROR` to use a custom mirror.

### 4.4 Tool Management

Tools are Python CLI applications installed in isolated environments. `uvx` is a shorthand for `uv tool run`.

```bash
# Run a tool without installing it
uvx ruff check .
uvx black --check .

# Install a tool globally
uv tool install ruff
uv tool install 'httpie>=3.0'

# List installed tools
uv tool list

# Upgrade tools
uv tool upgrade ruff
uv tool upgrade --all

# Uninstall
uv tool uninstall ruff
```

> [!TIP]
> Each tool gets its own isolated virtual environment under `~/.local/share/uv/tools/` (or `UV_TOOL_DIR`). Tools never conflict with each other or your projects.

### 4.5 Virtual Environments

```bash
# Create a venv (default: .venv)
uv venv

# Create with a specific Python version
uv venv --python 3.12

# Create at a custom path
uv venv /path/to/env

# Seed with pip and setuptools
uv venv --seed
```

### 4.6 pip-Compatible Interface

uv provides a `uv pip` subcommand that mirrors pip's interface:

```bash
# Install packages
uv pip install requests flask

# Install from requirements file
uv pip install -r requirements.txt

# Compile requirements (like pip-tools)
uv pip compile requirements.in -o requirements.txt

# Sync environment to requirements
uv pip sync requirements.txt

# Freeze installed packages
uv pip freeze

# List installed packages
uv pip list

# Show package details
uv pip show requests

# Check for broken dependencies
uv pip check

# Show dependency tree
uv pip tree

# Uninstall
uv pip uninstall requests
```

> [!WARNING]
> `uv pip` operates on the active virtual environment or system Python. It does not use project lockfiles — use `uv sync` for project-based workflows.

### 4.7 Building and Publishing

```bash
# Build sdist and wheel
uv build

# Build only a wheel
uv build --wheel

# Build a specific package in a workspace
uv build --package my-lib

# Publish to PyPI
uv publish

# Publish to a custom registry
uv publish --publish-url https://upload.pypi.org/legacy/ --token pypi-xxx
```

> [!IMPORTANT]
> uv supports trusted publishing on GitHub Actions and GitLab CI/CD. When running in those environments, set `--trusted-publishing always` to use OIDC tokens instead of API keys.

### 4.8 Security Auditing

```bash
# Audit project dependencies
uv audit

# Audit with a specific vulnerability database token
uv audit --github-token ghp_xxx

# Output in JSON format
uv audit --format json
```

### 4.9 Cache Management

```bash
# Show cache directory
uv cache dir

# Show cache size
uv cache size

# Clean entire cache
uv cache clean

# Clean cache for a specific package
uv cache clean requests

# Prune unreferenced cache entries
uv cache prune
```

### 4.10 Workspaces

Workspaces let you manage multiple related packages in a monorepo:

```toml
# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]
```

```bash
# List workspace members
uv workspace list

# Show workspace metadata
uv workspace metadata

# Run command in workspace context
uv run --package my-lib pytest

# Build a specific member
uv build --package my-lib
```

## 5. Common Tasks

### Create a FastAPI Application

**Goal:** Set up a new FastAPI project with development tooling.

**Steps:**
1. Initialize the project:
   ```bash
   uv init --app my-api
   cd my-api
   ```
2. Add dependencies:
   ```bash
   uv add fastapi uvicorn[standard]
   uv add --group dev pytest httpx
   ```
3. Run the development server:
   ```bash
   uv run uvicorn my_api:app --reload
   ```

**Verify:** Open `http://localhost:8000/docs` in a browser.

### Migrate from pip/requirements.txt to a uv Project

**Goal:** Convert an existing pip-based project to use uv's project management.

**Steps:**
1. Initialize in existing directory:
   ```bash
   uv init
   ```
2. Import existing dependencies:
   ```bash
   uv add $(cat requirements.txt | grep -v '^#' | tr '\n' ' ')
   ```
3. Lock and sync:
   ```bash
   uv lock
   uv sync
   ```
4. Remove old files:
   ```bash
   rm requirements.txt
   ```

**Verify:** `uv run python -c "import your_package"` succeeds.

### Use uv in Docker

**Goal:** Build a minimal Docker image with uv.

```dockerfile
FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Copy project files
WORKDIR /app
COPY pyproject.toml uv.lock ./

# Install dependencies (production only)
RUN uv sync --frozen --no-dev --no-editable

# Copy application code
COPY . .

CMD ["uv", "run", "python", "-m", "my_app"]
```

> [!TIP]
> Use `--frozen` in Docker to avoid lockfile updates. Use `--compile-bytecode` for faster cold starts in containers.

### Pin Dependencies for Reproducible Builds

**Goal:** Lock all transitive dependencies for CI/CD.

**Steps:**
1. Lock in development:
   ```bash
   uv lock
   ```
2. Commit `uv.lock` to version control.
3. In CI, install with `--locked`:
   ```bash
   uv sync --locked
   ```

**If it fails:** The lockfile is out of sync. Run `uv lock` locally and push the updated `uv.lock`.

### Use a Private Package Index

**Goal:** Install packages from a private PyPI-compatible registry.

```toml
# pyproject.toml
[[tool.uv.index]]
name = "private"
url = "https://private.pypi.example.com/simple"
```

**Authentication options:**

```bash
# Environment variable
export UV_INDEX_PRIVATE_USERNAME=user
export UV_INDEX_PRIVATE_PASSWORD=token

# Keyring
uv --keyring-provider subprocess pip install my-private-pkg

# URL credentials
uv pip install --index-url https://user:[email removed]/simple my-private-pkg
```

### Run a One-Off Script with Dependencies

**Goal:** Execute a Python script that declares its own dependencies inline.

```python
# fetch_data.py
# /// script
# requires-python = ">=3.11"
# dependencies = ["httpx", "rich"]
# ///

import httpx
from rich import print
data = httpx.get("https://httpbin.org/json").json()
print(data)
```

```bash
uv run fetch_data.py
```

uv creates an ephemeral environment, installs `httpx` and `rich`, and runs the script.

### Use PyTorch with the Correct CUDA Version

**Goal:** Install PyTorch with automatic CUDA detection.

```toml
# pyproject.toml
[tool.uv]
torch-backend = "auto"
```

```bash
uv add torch torchvision
```

> [!NOTE]
> The `torch-backend` setting is a preview feature. Enable preview mode with `uv --preview` or `UV_PREVIEW=1`.

### Set Up a Workspace with Multiple Packages

**Goal:** Manage a monorepo with shared dependencies.

```text
my-workspace/
├── pyproject.toml          # Root workspace
├── packages/
│   ├── core/
│   │   └── pyproject.toml
│   └── cli/
│       └── pyproject.toml
```

Root `pyproject.toml`:
```toml
[project]
name = "my-workspace"
version = "0.0.0"
requires-python = ">=3.11"

[tool.uv.workspace]
members = ["packages/*"]
```

Package `packages/cli/pyproject.toml`:
```toml
[project]
name = "my-cli"
version = "0.1.0"
dependencies = ["my-core"]

[tool.uv.sources]
my-core = { workspace = true }
```

```bash
uv lock    # Locks the entire workspace
uv sync    # Syncs all members
```

### Export for Non-uv Environments

**Goal:** Generate a `requirements.txt` for environments where uv isn't available.

```bash
# With hashes for security
uv export --format requirements-txt > requirements.txt

# Without hashes
uv export --format requirements-txt --no-hashes > requirements.txt

# For production only
uv export --format requirements-txt --no-dev > requirements-prod.txt
```

### Audit for Vulnerabilities

**Goal:** Check project dependencies for known CVEs.

```bash
uv audit
```

```text
Found 2 vulnerabilities in 1 package

  certifi (2024.2.2)
  ├── GHSA-xqr8-7jwr-rhp7 — certifi: removal of e-Tugra root certificate
  └── PYSEC-2024-91 — certifi uses vulnerable root certificates

  2 vulnerabilities found (fix available: update certifi to >=2024.7.4)
```

```bash
# Ignore a known vulnerability
uv audit --ignore GHSA-xqr8-7jwr-rhp7
```

### Format pyproject.toml

```bash
uv format
```

Normalizes the `pyproject.toml` — sorts dependencies, normalizes package names, and applies consistent formatting.

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
Problem?
├─ Installation issue → Check PATH, verify with `uv --version`
├─ Resolution failure → Check `uv lock -v` output, try `--exclude-newer`
├─ Build failure → Check build deps, try `uv pip install --no-build-isolation`
├─ Import error after sync → Check `uv sync` output, ensure correct venv
├─ Network/proxy issue → Try `--offline`, `--system-certs`, or proxy env vars
└─ Cache corruption → Run `uv cache clean` and retry
```

### Error: `No solution found when resolving dependencies`

**Cause:** Conflicting version requirements between packages.

**Solution:**
1. Run with verbose output to see the conflict:
   ```bash
   uv lock -v
   ```
2. Use constraints to narrow the resolution:
   ```bash
   uv add "package>=2.0,<3.0"
   ```
3. If a pre-release is needed:
   ```bash
   uv lock --prerelease allow
   ```

**Prevention:** Use `uv tree` regularly to understand your dependency graph.

### Error: `Failed to build <package>`

**Cause:** Missing system libraries or build tools required to compile a source distribution.

**Solution:**
1. Install system build tools:
   ```bash
   # Debian/Ubuntu
   sudo apt install build-essential python3-dev
   # macOS
   xcode-select --install
   ```
2. If the package has a wheel available, force it:
   ```bash
   uv add package --no-build
   ```

**Prevention:** Set `no-build-package = ["problematic-pkg"]` in `uv.toml` if wheels are available.

### Error: `error: externally-managed-environment`

**Cause:** Attempting to install into a system Python protected by PEP 668.

**Solution:**
```bash
# Use a virtual environment (preferred)
uv venv
uv pip install requests

# Or use uv's project management
uv init && uv add requests
```

**Prevention:** Always work within virtual environments or uv projects.

### Error: `No interpreter found for Python >=3.x`

**Cause:** The required Python version is not installed.

**Solution:**
```bash
uv python install 3.12
```

**Prevention:** Set `python-downloads = "automatic"` to let uv install Python as needed.

> [!WARNING]
> If `python-preference = "system-only"`, uv will not use managed Python installations. Change to `"managed"` or `"managed-only"` if you want uv to manage Python for you.

### Error: `Locked requirements are not up to date`

**Cause:** `pyproject.toml` was edited but `uv.lock` was not regenerated.

**Solution:**
```bash
uv lock
```

**Prevention:** Run `uv lock --check` in CI to catch lockfile drift.

### Error: SSL/TLS certificate verification failed

**Cause:** Corporate proxy intercepting HTTPS, or custom CA certificates.

**Solution:**
```bash
# Use system certificate store
export UV_SYSTEM_CERTS=true

# Or allow a specific insecure host
uv --allow-insecure-host private.pypi.example.com pip install package
```

**Prevention:** Configure `system-certs = true` and `allow-insecure-host` in `uv.toml`.

### Error: `Conflicting URLs for package`

**Cause:** Multiple sources resolve the same package to different URLs.

**Solution:**
1. Check your index configuration in `pyproject.toml`
2. Use `index-strategy = "first-index"` (default) to prevent dependency confusion
3. Pin specific sources:
   ```toml
   [tool.uv.sources]
   my-package = { index = "private" }
   ```

**Prevention:** Use explicit index assignments for private packages.

### Slow resolution or downloads

**Cause:** Network latency, too many indexes, or cold cache.

**Solution:**
1. Increase concurrency:
   ```toml
   concurrent-downloads = 32
   ```
2. Use `--offline` when the cache is warm
3. Set `index-strategy = "first-index"` to avoid querying all indexes

**Prevention:** Keep cache warm; use `uv cache prune` instead of `uv cache clean`.

> [!TIP]
> Run `uv lock -v` to see timing information for each resolution step. The first run populates the cache; subsequent runs are significantly faster.

## 7. FAQ

**Q: Does uv replace pip?**

Yes, for most workflows. `uv pip install`, `uv pip compile`, and `uv pip sync` provide a drop-in pip-compatible interface. The project-based workflow (`uv add`, `uv sync`, `uv run`) is recommended for new projects.

**Q: Does uv work with existing `requirements.txt` files?**

Yes. Use `uv pip install -r requirements.txt` or `uv pip sync requirements.txt`. To migrate to a uv project, run `uv init` and `uv add` your dependencies.

**Q: How do I use uv in CI/CD?**

Install uv, then use `uv sync --locked` to install from the lockfile:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --locked
uv run pytest
```

**Q: Can I use uv with Poetry or PDM projects?**

uv reads `pyproject.toml` but uses its own lockfile format (`uv.lock`). You can migrate by running `uv init` in an existing project and re-adding dependencies. Use `uv export` to generate `requirements.txt` for backward compatibility.

**Q: How does uv manage Python versions?**

uv downloads pre-built Python interpreters from `python-build-standalone` (maintained by Astral). They're stored in `~/.local/share/uv/python/`. Use `uv python install`, `uv python list`, and `uv python pin` to manage them.

**Q: Where does uv store data?**

| Data | Default Location (Linux) | Override |
|---|---|---|
| Cache | `~/.cache/uv` | `UV_CACHE_DIR` |
| Tools | `~/.local/share/uv/tools` | `UV_TOOL_DIR` |
| Managed Python | `~/.local/share/uv/python` | `UV_PYTHON_INSTALL_DIR` |
| Tool binaries | `~/.local/bin` | `UV_TOOL_BIN_DIR` |

**Q: What is `uvx`?**

`uvx` is an alias for `uv tool run`. It runs a Python CLI tool in an ephemeral environment without permanently installing it — similar to `npx` for Node.js.

**Q: Can I use uv with Jupyter notebooks?**

Yes. Install Jupyter as a tool: `uv tool install jupyter`. Or within a project: `uv add jupyter` then `uv run jupyter lab`.

**Q: How do I configure authentication for private indexes?**

Options include:
- URL credentials: `https://user:token@host/simple`
- Environment variables: `UV_INDEX_<NAME>_USERNAME` / `UV_INDEX_<NAME>_PASSWORD`
- Keyring: `--keyring-provider subprocess`
- `.netrc` file
- `uv auth login` (preview feature)

**Q: What is the difference between `uv lock` and `uv pip compile`?**

`uv lock` creates a cross-platform lockfile (`uv.lock`) from your `pyproject.toml` project. `uv pip compile` creates a `requirements.txt` from input `.in` files — it's the pip-tools replacement. Use `uv lock` for projects; use `uv pip compile` for legacy workflows.

**Q: Does uv support editable installs?**

Yes. Project packages are installed in editable mode by default during `uv sync`. For `uv pip`, use `uv pip install -e .`.

**Q: How do dependency groups work?**

Dependency groups (PEP 735) let you organize development dependencies:
```toml
[dependency-groups]
dev = ["pytest", "ruff"]
docs = ["sphinx", "furo"]
```
Install specific groups with `uv sync --group dev` or `uv sync --group docs`.

**Q: What is `--frozen` vs `--locked`?**

- `--locked`: Asserts that `uv.lock` is up-to-date with `pyproject.toml`. Fails if not.
- `--frozen`: Skips lockfile validation entirely. Uses whatever is in `uv.lock` without checking.

Both skip re-resolving. Use `--locked` in CI; use `--frozen` for speed when you know the lock is fine.

---

_Generated May 2026 from astral-sh/uv at 9c0eec6. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._