uv in 30 Minutes: The Definitive Guide

From Tool Soup to a Unified Python Engine. Learn how uv replaces pyenv, pip, and venv with Rust-powered speed.

1. The Philosophy

uv is an all-in-one Python project manager written in Rust. It is designed to be "unreasonably fast"—often 10–100× faster than standard tools.

In the past, you needed a "tool soup": pyenv for versions, pip for packages, and venv for environments. uv replaces them all.

2. Why is it different?

Feature Standard (pip/venv) Modern (uv)
Speed Slow/Sequential Parallel Rust Engine
Disk Space Duplicates files Global Cache (Hardlinks)
Locking Manual/Third-party Native uv.lock
Python Installation Manual Automatic Management

3. Installation

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

4. The Project Workflow

Step 1: Initialization

uv init my-app
cd my-app

Step 2: Adding Packages

uv add requests pandas
uv add --dev pytest

Step 3: Running Code

uv run main.py

The Magic: You never have to "activate" a virtual environment. uv run ensures your environment is synced perfectly before it starts.

5. The Anatomy of a Project

Every uv project centers around four key files:

  • pyproject.toml: The Project Brain. You edit this to declare your dependencies.
  • uv.lock: The Source of Truth. An auto-generated map of every exact version used. Do not edit manually.
  • .python-version: Tells uv exactly which version of Python to download and use.
  • .venv/: The local sandbox where your links live. It's disposable and fast to recreate.

6. Advanced "Goodness"

Single-File Scripts (PEP 723)

Add metadata directly to a script to make it portable:

# /// script
# dependencies = ["httpx"]
# ///
import httpx
print(httpx.get("https://google.com").status_code)

Run it with uv run script.py and uv handles the dependencies automatically.

Global Tool Runner

Run tools without installing them into your project:

uvx ruff check .

Related Articles