Introduction to uv and pyproject.toml

This guide introduces uv, a modern Python package manager, and pyproject.toml, the standard configuration file for Python projects.

What is uv?

uv is a fast Python package and project manager written in Rust. It replaces multiple tools you may have used before:

pip for installing packages
virtualenv or venv for creating virtual environments
pip-tools for dependency resolution

uv is significantly faster than these tools and provides a consistent interface for managing Python projects.

What is pyproject.toml?

pyproject.toml is the standard configuration file for Python projects, defined by PEP 518 and PEP 621. It replaces older configuration files like setup.py, setup.cfg, and requirements.txt.

A minimal pyproject.toml looks like this:

[project]
name = "my-project"
version = "0.1.0"
description = "A short description of your project"
requires-python = ">=3.13"
dependencies = [
    "httpx>=0.28.1",
    "loguru>=0.7.3",
]

Key Sections

Section	Purpose
`[project]`	Core metadata: name, version, dependencies
`[project.scripts]`	Command-line entry points
`[tool.*]`	Configuration for tools like pytest, ruff, mypy
`[build-system]`	Build backend configuration

Installing uv

macOS and Linux

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

Windows

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

Verify Installation

uv --version

Essential uv Commands

Creating a New Project

uv init my-project
cd my-project

This creates a new directory with pyproject.toml, .python-version, and a basic project structure.

Adding Dependencies

uv add httpx
uv add loguru

Dependencies are added to pyproject.toml and a uv.lock file is created to lock exact versions.

Adding Development Dependencies

uv add --dev pytest
uv add --dev ruff

Development dependencies are only needed for testing and development, not for running the application.

Removing Dependencies

uv remove httpx

Syncing Dependencies

uv sync

This installs all dependencies from uv.lock into the virtual environment. Run this when cloning a project or after pulling changes.

Running Python Scripts

uv run python script.py

The uv run command ensures the virtual environment is activated and dependencies are synced before running your command.

Running Modules

uv run python -m mypackage.module

This is the preferred way to run modules, as it handles import paths correctly.

Running Tests

uv run pytest

Or with specific options:

uv run pytest -v tests/

Project Structure Example

A typical project using uv looks like this:

my-project/
├── pyproject.toml      # Project configuration
├── uv.lock             # Locked dependency versions
├── .python-version     # Python version for the project
├── .venv/              # Virtual environment (created by uv)
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

The uv.lock File

The uv.lock file contains the exact versions of all dependencies and their transitive dependencies. This ensures reproducible builds across different machines.

You should commit uv.lock to version control to ensure all team members use the same dependency versions.

Common Workflows

Starting a New Project

uv init my-project
cd my-project
uv add httpx loguru
uv run python main.py

Cloning an Existing Project

git clone <repository-url>
cd <project-directory>
uv sync
uv run python -m mypackage

Updating Dependencies

uv lock --upgrade
uv sync

Comparison with Other Tools

Task	pip/venv	uv
Create environment	`python -m venv .venv`	`uv venv` (automatic)
Install package	`pip install httpx`	`uv add httpx`
Install from file	`pip install -r requirements.txt`	`uv sync`
Run script	`source .venv/bin/activate && python script.py`	`uv run python script.py`

Additional Resources

back