uv

---
name: uv
description: "Use when managing Python projects with uv: fast virtualenvs, dependency resolution, lockfiles, and a pip-compatible interface from Astral."
source: https://docs.astral.sh/uv/
generated: 2026-07-02T18:43:44.295Z
category: tool
audience: engineers
---

## When to use

- Creating and managing Python virtual environments quickly
- Installing and locking project dependencies via pyproject.toml
- Replacing pip, pip-tools, and venv with one fast tool
- Pinning and switching Python interpreter versions per project

## Key concepts

### Project vs pip interface

uv has a project workflow (uv add/sync/lock around pyproject.toml) and a low-level pip-compatible interface (uv pip install/compile) for existing workflows.

### uv.lock

A universal, cross-platform lockfile uv generates and respects to make installs reproducible; managed automatically by uv sync/add.

### Managed Python

uv can download and manage standalone CPython builds, so `uv python install 3.12` provisions interpreters without system Python.

### .venv auto-discovery

Project commands create and use a .venv in the project root automatically; uv run executes inside it without manual activation.

### uv pip compile

Compiles requirements.in into a fully pinned requirements.txt, a drop-in faster pip-tools replacement.

### Global cache

uv hard-links/copies from a shared cache for fast, deduplicated installs across projects.

## API reference

```
uv venv [PATH] [--python X.Y]
```

Create a virtual environment, optionally pinning the interpreter version.

```
uv venv --python 3.12
source .venv/bin/activate
```

```
uv pip install PACKAGE
```

pip-compatible install into the active or project environment.

```
uv pip install 'requests>=2.31'
uv pip install -r requirements.txt
```

```
uv add / uv sync / uv lock
```

Project workflow: add a dependency to pyproject.toml, sync the env to the lockfile, and regenerate the lock.

```
uv init myapp
cd myapp
uv add fastapi
uv sync
```

```
uv run COMMAND
```

Run a command inside the project environment, syncing first if needed.

```
uv run python main.py
uv run pytest
```

## Gotchas

- `uv pip install` does not modify pyproject.toml or uv.lock; use `uv add` for project dependencies you want tracked.
- uv pip operates on the active/discovered environment, not the global system Python, so activate or use --python deliberately.
- uv sync prunes packages not in the lockfile by default, removing anything you installed manually with uv pip.
- uv run auto-syncs the environment, so it may install/uninstall packages before running your command.
- uv venv does not auto-activate; you still must source the activate script or rely on uv run.
- Managed Python interpreters are separate from system Python; mixing them can cause confusing version mismatches.

---
Generated by SkillMake from https://docs.astral.sh/uv/ on 2026-07-02T18:43:44.295Z.
Verify against source before relying on details.

File: ~/.claude/skills/uv/SKILL.md