# Deep Dive: UV Package Manager
**Source**: `docs.astral.sh`
**Author**: Astral (creators of Ruff)
**Current Version**: (As of Retrieval)
## Executive Summary
**UV** is an extremely high-performance Python package and project manager, written in Rust. It is designed to be a single, unified tool that replaces a fragmented ecosystem of Python tools including `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, and `virtualenv`.
Its primary selling points are **speed** (10-100x faster than pip) and **reliability** (universal lockfiles, isolated environments).
---
## 1. Core Architecture & Philosophy
### The "One Tool" Approach
UV effectively collapses the Python workflow stack:
- **Installer**: Replaces `pip`
- **Environment Manager**: Replaces `virtualenv` / `venv`
- **Python Version Manager**: Replaces `pyenv`
- **Dependency Resolver**: Replaces `pip-tools`
- **Project Manager**: Replaces `poetry` / `pdm`
- **Tool Runner**: Replaces `pipx`
### Performance
UV is powered by a global cache and efficient dependency resolution algorithms implemented in Rust. It utilizes copy-on-write (reflink) on supported filesystems to make creating virtual environments nearly instantaneous.
---
## 2. Project Management (`uv init`, `uv lock`)
UV adopts a modern project workflow centered around `pyproject.toml`.
### Workflow
1. **Initialization**:
```bash
uv init my-project
cd my-project
```
This creates `pyproject.toml`, `.python-version`, and a basic `main.py`.
2. **Adding Dependencies**:
```bash
uv add requests
uv add --dev pytest
```
This updates `pyproject.toml` and automatically creates/updates the `uv.lock` file.
3. **Running Code**:
```bash
uv run main.py
# OR
uv run flask run
```
`uv run` ensures the environment is in sync with the lockfile before execution. It handles creating the virtual environment (`.venv`) automatically if it's missing.
4. **Syncing**:
```bash
uv sync
```
Explicitly syncs the environment with the lockfile, installing/uninstalling packages as needed.
### File Structure
- `pyproject.toml`: Broad dependency requirements.
- `uv.lock`: Exact resolved versions (cross-platform).
- `.venv/`: The local virtual environment (managed by UV).
- `.python-version`: Specifies the pinned Python version for the project.
---
## 3. Script Management (PEP 723)
UV introduces a revolutionary way to handle single-file scripts without needing a full project setup.
### Inline Metadata
You can declare dependencies directly inside a Python script:
```python
# script.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
# ... code ...
```
### Execution
Run the script seamlessly:
```bash
uv run script.py
```
UV will:
1. Download the required Python version (if missing).
2. Create an ephemeral environment with the specified dependencies.
3. Run the script.
4. Cache the environment for future runs.
### Managing Script Dependencies
You can add dependencies to a script without editing it manually:
```bash
uv add --script script.py requests
```
---
## 4. Tool Management (`uvx`, `uv tool`)
UV replaces `pipx` for running and installing command-line tools.
### Ephemeral Execution (`uvx`)
Run a tool without installing it globally:
```bash
uvx ruff check
uvx pycowsay "Hello World"
```
This is an alias for `uv tool run`.
### Persistent Installation
Install a tool to be available in your PATH:
```bash
uv tool install black
```
This isolates the tool in its own environment to prevent dependency conflicts.
---
## 5. Python Version Management
UV can manage Python installations itself, removing the need for `pyenv`.
- **Install a version**: `uv python install 3.12`
- **Pin a version**: `uv python pin 3.11` (creates `.python-version`)
- **Run with specific version**: `uv run --python 3.10 script.py`
---
## 6. The Pip Interface (Legacy/Migration)
For users not ready to switch to the full project manager workflow, UV provides a drop-in replacement for `pip`.
```bash
uv pip install requests
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
```
This ensures you can get the speed benefits of UV even in legacy setups or CI/CD pipelines that rely on `requirements.txt`.
---
## Key Commands Cheat Sheet
| Action | Command |
| :--- | :--- |
| **New Project** | `uv init <name>` |
| **Add Package** | `uv add <package>` |
| **Run Command** | `uv run <command>` |
| **Run Script** | `uv run <script.py>` |
| **Update Lockfile** | `uv lock` |
| **Sync Environment** | `uv sync` |
| **Run Tool (Once)** | `uvx <tool>` |
| **Install Tool** | `uv tool install <tool>` |
| **Install Python** | `uv python install <version>` |
