Unified Python Management with uv: A High-Performance Tutorial

Prerequisites

To follow this guide, you should have a basic understanding of the Python ecosystem, including how to use the terminal and the purpose of a pyproject.toml file. While no specific version of Python is required to start—since uv can install Python for you—having a shell environment like Zsh or Bash is necessary.

Key Libraries & Tools

• uv: An extremely fast Python package and project manager.
• Ruff: An extremely fast Python linter and formatter, also by Astral.
• Homebrew: A macOS package manager used for easy installation.
• Cargo: The Rust package manager, used if building uv from source.

Code Walkthrough

Installation

On macOS, install via Homebrew:

brew install uv

Alternatively, use a standalone script for any OS:

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

Project Initialization

Create a new project structure with a standard pyproject.toml and a managed virtual environment:

uv init my-project
cd my-project

This command generates a boilerplate Git setup, a .python-version file, and a basic hello.py script.

Managing Dependencies

Add and remove packages seamlessly. uv automatically updates your requirements and syncs the environment:

uv add pandas fast-api
uv remove sql-alchemy

Executing Code

Run scripts directly within the context of your managed environment without manually activating it:

uv run hello.py

Syntax Notes

uv uses a command structure reminiscent of Cargo or npm. The uvx command (shorthand for uv tool run) allows for one-off execution of CLI tools like Ruff without permanently adding them to your project dependencies.

Practical Examples

In monorepo environments, uv supports Workspaces. This allows multiple projects to share a single lockfile and virtual environment, reducing disk usage and ensuring version consistency across different microservices or internal libraries.

Tips & Gotchas

• Shell Completion: Enable tab-completion for faster terminal navigation by running uv generate-shell-completion zsh and adding it to your config.
• Build Systems: Currently, uv relies on backends like hatchling for building packages. It does not yet include a built-in Rust-based build backend, though this is actively being developed.
• Python Versions: Use uv python install 3.13 to manage runtimes without needing pyenv.