Python Development Tooling How-To Guides

Practical guides for accomplishing specific tasks with Python development tools like uv, ruff, and pytest.

How-to guides answer specific questions for someone already past the basics. Each page solves one task and gets out of the way.

If the tool is unfamiliar, start with a Tutorial. For technical detail on a specific tool, see Reference.

Pages are grouped by task below. Pick a group, scan the titles, and jump to the one you need.

Installation & Setup

Install uv, Python, and ML packages on every platform

How to add Python to your system path with uv

Make uv-installed Python versions globally accessible on your system PATH.

How to Install bitsandbytes

Install bitsandbytes for quantized LLM inference, with the correct CUDA backend, using pip, uv, or conda.

How to Install DeepSpeed

Install Microsoft's DeepSpeed distributed training library, handling its JIT-compiled CUDA ops and system dependencies.

How to Install Flash-Attention

Install flash-attn without waiting hours for a CUDA compilation, using prebuilt wheels or conda-forge.

How to Install llama-cpp-python

Install llama-cpp-python with GPU acceleration for CUDA or Metal, using prebuilt wheels or compiling from source.

How to install Python CLI tools without Python

Install any Python CLI tool from PyPI without a local Python or uv installation using uvx.sh.

How to install Python with uv

Install and manage Python versions using uv, which downloads interpreters automatically when needed.

How to Install PyTorch with uv

Configure uv to install the correct PyTorch build for your hardware, whether you need CUDA, ROCm, or CPU-only wheels.

How to Install RAPIDS with uv

Configure uv to install NVIDIA RAPIDS libraries like cuDF and cuML with the correct CUDA version for your system.

How to Install Triton

Install OpenAI's Triton GPU compiler as a PyTorch dependency or standalone package on Linux.

How to install uv

Install uv, the fast Python package manager, on macOS, Linux, or Windows. Which method to use, when to skip pip, and how to fix `uv: command not found`.

How to install uv on Linux

Install uv on Linux using the standalone installer, Homebrew, or pip.

How to install uv on macOS

Install uv on macOS using the standalone installer, Homebrew, or pip.

How to install uv on Windows

Install uv on Windows using the standalone installer, WinGet, Scoop, or pip.

How to Install xformers

Install Meta's xformers library with the correct PyTorch and CUDA versions using pip, uv, or conda-forge.

Editors & AI Assistants

Configure VS Code, Cursor, Claude Code, Codex, and Copilot

How to configure Claude Code to use uv

Create a CLAUDE.md file so Claude Code automatically uses uv instead of pip for Python package management.

How to configure Claude Code to use virtual environments

Configure Claude Code to use Python virtual environments through `uv run`, a CLAUDE.md interpreter rule, a `.claude/settings.json` `env` block, and a PreToolUse hook. Shell activation cannot persist between commands; these patterns do.

How to configure Cursor for a uv project

Set up Cursor editor to work with a uv-managed Python project, including interpreter selection, Ruff formatting, pytest integration, and AI agent rules.

How to configure Cursor rules to use uv

Set up Cursor editor rules so the AI assistant uses uv instead of pip for Python projects.

How to configure Ruff with Claude Code

Wire Ruff into Claude Code through CLAUDE.md rules, the /astral:ruff skill, an auto-format PostToolUse hook, and a pre-commit gate so every Python edit is linted and formatted.

How to configure VS Code for a uv project

Set up Visual Studio Code to work with a uv-managed Python project, including interpreter selection, Ruff formatting, and pytest integration.

How to create a new Python project with Codex

Use OpenAI Codex with the Modern Python Project Setup Guide to scaffold uv-based Python projects.

How to install the Astral plugins for Claude Code

Install Astral's official Claude Code plugin to get skills and a language server for uv, ruff, and ty.

How to use Python skills with Claude Code

Install the Astral plugin for uv, Ruff, and ty, write your own SKILL.md for Python conventions, and choose between skills, hooks, and CLAUDE.md.

How to use the pydevtools CLAUDE.md template for Python projects

A ready-to-use CLAUDE.md file that teaches Claude Code to use uv, ruff, pytest, and modern Python tooling by default.

How to write Claude Code hooks for Python projects

Write PreToolUse, PostToolUse, UserPromptSubmit, and Stop hooks that enforce uv, auto-format with Ruff, run ty after every turn, and add project context to Claude Code sessions.

Migration

Move existing projects from older tools to uv, ty, and pyproject.toml

How to convert a script with requirements.txt to PEP 723 inline metadata

Move a one-off Python script's dependencies out of a sidecar requirements.txt and into a PEP 723 inline metadata block uv can read.

How to migrate from Black to Ruff formatter

Replace Black with Ruff's formatter by translating pyproject.toml config, updating pre-commit hooks, and updating CI.

How to migrate from mypy to ty

Evaluate and plan migration from mypy to ty, Astral's faster Python type checker.

How to migrate from Pipenv to uv

Convert a Pipenv project to uv by translating Pipfile to pyproject.toml and replacing Pipenv commands.

How to migrate from Poetry to uv

Convert a Poetry-managed project to uv using the migrate-to-uv tool.

How to migrate from Pyright to ty

Evaluate and plan migration from Pyright to ty, Astral's faster Python type checker.

How to migrate from requirements.txt to pyproject.toml with uv

Convert a requirements.txt project to pyproject.toml with uv. Run uv init --bare, then uv add -r requirements.txt to import pins and generate a lockfile.

How to migrate from setup.py to pyproject.toml

Convert a legacy setup.py project to pyproject.toml using standard Python packaging metadata.

How to migrate from uv to pip

Move a uv-managed project to pip and pyenv (or python.org on Windows) by leaning on PEP 621, PEP 735, and PEP 751 in pyproject.toml.

How to replace Black, isort, flake8, and pyupgrade with Ruff

Consolidate a Python project's lint stack onto Ruff by mapping rule prefixes, translating configuration, and updating pre-commit and CI hooks.

How to switch from pyenv to uv for managing Python versions

Remove pyenv and replace it with uv for faster Python version management.

How to upgrade setup-uv from v7 to v8

Migrate astral-sh/setup-uv from v7 to v8 in GitHub Actions, with SHA pinning for supply-chain security.

pip to uv: a command cheatsheet

Side-by-side mapping of pip, venv, pyenv, pip-tools, and pipx commands to their uv equivalents.

Daily Workflow

Run, lock, upgrade, and manage day-to-day work in a uv project

How to change the Python version of a uv project

Update, upgrade, or switch the Python version for a uv project by pinning with .python-version and editing pyproject.toml.

How to create and use a Python virtual environment with venv

Use Python's built-in venv module to create, activate, and reset a virtual environment on macOS, Linux, and Windows.

How to customize uv's virtual environment location

Override the default .venv location for uv projects using command flags or environment variables.

How to distribute internal Python CLI tools with uv

Roll out an internal Python CLI across your team from a private PyPI index, a git repository, or a pre-built wheel using uv tool install. Pin versions, push upgrades, and bootstrap new machines.

How to install from a pylock.toml lockfile with pip

Install dependencies from a PEP 751 pylock.toml file using pip 26.1's experimental -r support, with the --no-deps flag that keeps the install strictly locked.

How to keep Python up to date with uv python upgrade

Run `uv python upgrade` to fetch the latest patch release for every uv-managed Python and have existing virtual environments follow.

How to manage cross-repository Python dependencies with uv

Share Python packages across separate git repositories using uv. Use editable local paths for day-to-day development, git references for branch pinning, and [tool.uv.sources] to toggle between git and published versions.

How to profile a Python script with py-spy

Record a flame graph, view it in speedscope, and attach to a running process with py-spy, the low-overhead sampling profiler for Python.

How to require a virtualenv when installing packages with pip?

Configure pip to refuse package installation outside a virtual environment using PIP_REQUIRE_VIRTUALENV.

How to Run a Jupyter Notebook with uv

Launch Jupyter notebooks in isolated uv environments with automatic dependency management.

How to Run a Python REPL with uv

Start an interactive Python REPL session using uv run python.

How to run the IPython shell in your uv project

Use IPython in a uv project without adding it as a permanent dependency.

How to set up a Python monorepo with uv workspaces

Configure uv workspaces to manage multiple Python packages in a single repository with shared dependencies and a unified lockfile.

How to Set Up Auto-Reload for Python Projects

Practical instructions for enabling automatic code reloading in Django, Flask, FastAPI, generic scripts, and IPython.

How to upgrade uv

Update uv to the latest version using the method matching your original installation.

How to Use `--exclude-newer` for Reproducible Python Environments

Use uv's --exclude-newer flag to ignore package versions published after a specific date.

How to use a uv lockfile for reproducible Python environments

Create and use uv.lock to ensure identical dependency versions across machines and deployments.

How to use free-threaded Python in a uv project

Install Python 3.14's free-threaded build, pin it in an existing uv project, and check whether your dependencies ship free-threaded wheels.

How to use pip in a uv virtual environment

Add pip to a uv virtual environment when tools like Jupyter require direct pip access.

How to Use Poe the Poet as a Task Runner with uv

Set up Poe the Poet as a task runner in uv projects for common development commands.

How to use private package indexes with uv

Configure uv to install packages from private registries like AWS CodeArtifact, Google Artifact Registry, JFrog Artifactory, Azure Artifacts, and Sonatype Nexus. Handle corporate proxies and TLS certificates.

How to use uv to speed up Hatch

Configure Hatch to use uv for faster dependency resolution and installation.

How to use uv to speed up PDM

Configure PDM to use uv for faster dependency resolution and installation.

How to write self-contained Python scripts using PEP 723 inline metadata

Create Python scripts with PEP 723 inline metadata that declare their own dependencies for uv.

Testing

Run pytest with uv, parallelize, and matrix-test against Python versions

How to replace tox with uv and a Makefile

Use uv's UV_PROJECT_ENVIRONMENT variable and a pattern-rule Makefile to orchestrate multi-version Python tests without tox, then run the matrix in parallel with make -j.

How to run tests in parallel with pytest-xdist

Speed up your pytest test suite by running tests across multiple CPU cores using pytest-xdist.

How to Run Tests Using uv

Run pytest and other test frameworks in uv-managed Python projects.

How to Test Against Multiple Python Versions Using uv

Run your test suite across multiple Python versions with uv, from one-off checks to automated multi-version testing.

How to use uv to speed up tox

Install the tox-uv plugin to replace pip and virtualenv with uv, making tox environment creation and dependency installation dramatically faster.

Linting, Formatting & Type Checking

Configure Ruff, ty, and mypy across new or existing projects

How to add type annotations to a Python project with pyrefly infer

Use Pyrefly's infer command to write type annotations into existing Python source files.

How to configure mypy strict mode

Enable mypy's strict mode to catch more type errors, and learn how to adopt it gradually in existing projects.

How to configure recommended Ruff defaults

Configure Ruff with a curated set of linting rules that go beyond defaults for new Python projects.

How to configure Ruff for Django

Enable Ruff's flake8-django (DJ) rules, ignore the right files, and keep auto-generated migrations and settings.py from drowning a Django project in lint noise.

How to Enable Ruff Security Rules

Catch hardcoded secrets, SQL injection, insecure deserialization, and other security issues in Python code using Ruff's flake8-bandit rules.

How to format pyproject.toml with taplo

Use taplo to automatically format and validate pyproject.toml files in Python projects managed with uv.

How to gradually adopt type checking in an existing Python project

Add type checking to an existing Python codebase without fixing every error at once.

How to sort Python imports with Ruff

Automatically organize and sort Python import statements using Ruff's isort-compatible rules.

How to try the ty type checker

Install and run ty, Astral's fast Python type checker, in your project using uv.

Packaging & Publishing

Lock, sign, scan, and publish Python packages to PyPI

How to add dynamic versioning to uv projects

Set up Git-based automatic version numbering in uv projects using uv-dynamic-versioning.

How to Build Multi-Platform Wheels with cibuildwheel

Build Python wheels for Linux, macOS, and Windows in GitHub Actions using cibuildwheel, then publish to PyPI.

How to Create and Distribute a Python CLI Tool

Define a console_scripts entry point in pyproject.toml, publish to PyPI, and let users run your tool with uvx or uv tool install.

How to Host Your Own Python Package Index

Run devpi, pypiserver, or bandersnatch to host private Python packages or mirror PyPI. Decide which one fits, set up devpi, and configure uv and pip to install from it.

How to Protect Against Python Supply Chain Attacks with uv

Use uv's dependency cooldown feature to delay installation of newly-published packages, giving the community time to detect malicious versions.

How to Publish Python Packages with Digital Attestations

Add PEP 740 digital attestations to your PyPI releases so consumers can verify package provenance through pylock.toml.

How to Publish to PyPI with Trusted Publishing

Replace long-lived PyPI API tokens with OIDC-based trusted publishing using GitHub Actions and uv.

How to Publish to TestPyPI with uv

Upload a Python package to TestPyPI with uv to rehearse a PyPI release, then install it back to verify before pushing to the real index.

How to Scan Python Dependencies for Vulnerabilities

Check Python project dependencies for known security vulnerabilities using uv audit and pip-audit.

How to Set Up Documentation for a Python Package with Sphinx or MkDocs

Pick between Sphinx and MkDocs, scaffold a docs site from a uv project, pull docstrings into the site with autodoc or mkdocstrings, and preview locally before hosting.

How to Verify Dependencies with Hashes in uv

Verify package integrity at install time using dependency hashes in uv's lockfile and compiled requirements.

How to write install instructions for a Python library

Show readers (and their AI agents) how to install your library with uv, not just pip. The install snippet in your README is the first thing both will copy.

CI, Hooks & Containers

Pre-commit, GitHub Actions, Docker, and CI integration

How to Build Read the Docs with uv

Configure .readthedocs.yaml to install Python dependencies with uv sync or uv pip install, including dependency groups and lockfile-based reproducibility.

How to pin GitHub Actions by SHA for Python projects

Pin GitHub Actions to commit SHAs instead of mutable tags to protect your Python CI from supply-chain attacks.

How to put your Python project on GitHub

Initialize a Git repository and push a uv-based Python project to GitHub for the first time.

How to set up pre-commit hooks for a Python project

Install and configure pre-commit to automatically run linters, formatters, and checks before every Git commit.

How to set up prek hooks for a Python project

Install and configure prek, a faster drop-in replacement for pre-commit, to run linters and formatters before every Git commit.

How to use ty in CI

Set up ty type checking in GitHub Actions, GitLab CI, and other CI platforms with the right output format for inline annotations.

How to use uv in a Dockerfile

Build Python Docker images with uv for fast, reproducible dependency installs.

Troubleshooting

Diagnose and fix common errors with uv, pip, and pytest

Please submit corrections and feedback...