modern-python-toolchain

Modern Python Toolchain

A guide for setting up Python projects with modern, fast tooling: uv (package/project manager), ruff (linter/formatter), and pyright (type checker).

Installing uv

uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc.

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew (macOS)
brew install uv

After installation, restart your shell or run source $HOME/.local/bin/env (the installer prints the exact command).

For detailed information: https://docs.astral.sh/uv/

---

uv basics

Python version

Pin a single Python minor version. The recommended default is 3.12 (broadest ecosystem support — PyTorch, CUDA images, downstream libraries). Python 3.14 is the latest stable; prefer it for new projects unless you depend on packages that haven't added 3.14 support yet.

# pyproject.toml
requires-python = "==3.12.*"

Install Python via uv (no system Python needed):

uv python install 3.12

Creating a new project

uv init                       # Create new project with pyproject.toml
uv init -p 3.12               # Specify Python version

Common commands

uv add requests               # Add dependency
uv add --dev ruff "pyright[nodejs]"  # Add dev dependencies
uv remove requests            # Remove dependency
uv sync                       # Install from lockfile
uv run COMMAND                # Run command in project environment
uv run script.py              # Run a script
uv run python -c "..."        # Run Python one-liner
uvx TOOL ARGS                 # Run a tool without installing it

Rules

• Never use pip in uv projects — always uv add for packages.
• Never run python script.py directly — always uv run script.py to ensure the correct environment. For one-liners use uv run python -c "...".
• Don't manually manage environments with python -m venv or source .venv/bin/activate — uv handles this automatically.
• uvx runs tools from PyPI by package name without installing them permanently.