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 Hugging Face Transformers with uv

Install Hugging Face Transformers with uv for CPU inference, GPU training with CUDA, or quantized model loading with accelerate and bitsandbytes.

How to Install JAX with uv

Install JAX for CPU, NVIDIA GPU (CUDA 12/13), or Google TPU with uv. JAX uses pip extras; no custom index configuration needed.

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 CPython interpreters with `uv python install`. No system Python or admin privileges required.

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 32-bit Raspberry Pi OS

Install uv on 32-bit Raspberry Pi OS, work around the libc detection and 32-bit-userland bugs, and configure piwheels for armv7l wheels.

How to install uv on Linux

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

How to install uv on macOS

How to install uv on macOS with the standalone installer, Homebrew, or pip. Covers Apple Silicon, PATH setup, and troubleshooting.

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.

How to run Python scripts on a Raspberry Pi with uv

Install uv on Raspberry Pi OS, then run Python scripts on a Pi without tripping the externally-managed-environment error.

How to Serve LLMs Locally with vLLM and uv

Install vLLM with uv, then serve LLMs through an OpenAI-compatible API.

How to use picamera2 and GPIO with uv on Raspberry Pi

Build a uv-managed environment on a Raspberry Pi that can import picamera2, libcamera, and gpiozero alongside pip-installed dependencies.

How to use uv on NixOS

Install uv on NixOS, fix the dynamic-linker error that breaks managed Python downloads, and pin uv per project with a flake.nix dev shell.

How to Use uv on Windows ARM64

Install uv on Windows ARM64 and decide when to use native aarch64 Python instead of the default emulated x86_64 build.

Editors & AI Assistants

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

How to configure Claude Code to run your pre-commit hooks

Wire pre-commit into Claude Code's edit cycle with a Stop hook and a PostToolUse hook so the agent fixes violations against the exact hooks that gate your commit.

How to configure Claude Code to run your pytest suite

Wire pytest into Claude Code with a /test slash command, a Stop hook that gates every turn, and short-traceback flags that turn a screen of pytest output into the few lines the agent can act on.

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

Make Claude Code use virtual environments via `uv run`, CLAUDE.md rules, env config, or PreToolUse hooks. Shell activation doesn't persist.

How to configure Claude Code with a Python type checker

Integrate type checkers with Claude Code using CLAUDE.md, language-server plugins, Stop hooks, and pre-commit to surface errors during turns, not after.

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 for pytest

Enable pytest in Cursor's Testing sidebar, configure test discovery with pyproject.toml, and add a Cursor rule so the AI agent always runs tests via uv.

How to configure Cursor for Ruff

Configure the Ruff extension in Cursor for format-on-save, auto-fix, and import sorting with .vscode/settings.json setup.

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 Helix for a uv Project

Set up Helix editor to work with a uv-managed Python project, including Ruff formatting, ty type checking, and virtual environment detection.

How to configure PyCharm for a uv project

Set up PyCharm to work with a uv-managed Python project: select the .venv interpreter, enable Ruff and pytest, and use the 2026.1.1 workspace beta.

How to configure Ruff with Claude Code

Wire Ruff into Claude Code via CLAUDE.md rules, PostToolUse hooks, and pre-commit for real-time linting.

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 configure VS Code for type checking in a uv project

Set up type checking in VS Code for uv projects using ty or mypy extensions, including daemon mode and workspace diagnostics.

How to Configure Zed for a uv Project

Configure Zed editor for uv projects: virtual environment detection, Ruff formatting, basedpyright type checking, and task runner setup.

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 OpenAI's Astral plugins for Claude Code

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

How to Set Up CLAUDE.md for a Python Project

CLAUDE.md template for Python projects: configures Claude Code to use uv, Ruff, pytest, and modern Python tooling by default.

How to stop AI agents from bypassing pre-commit hooks

Block `git commit --no-verify` in Claude Code with CLAUDE.md, permissions, hooks, PATH shims, and CI.

How to use Python skills with Claude Code

Write reusable Claude Code procedures as SKILL.md files. Install Astral plugin for uv/Ruff/ty. Layer with hooks.

How to use uv with VS Code devcontainers

Configure a VS Code devcontainer with uv so a team shares the same Python environment from one lockfile.

How to write Claude Code hooks for Python projects

Write Claude Code hooks for uv enforcement, Ruff auto-format, type checking, and project context injection into 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 conda to pixi

Convert an existing conda environment.yml to a pixi project with pixi.toml, a lockfile, tasks, and project-local environments.

How to migrate from mypy to Pyrefly

Auto-migrate mypy config with `pyrefly init`, baseline new diagnostics, switch CI incrementally.

How to migrate from mypy to ty

Evaluate and plan migration from mypy to ty, OpenAI'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

Migrate a Poetry project to uv with migrate-to-uv. Covers pyproject.toml conversion, lockfiles, private indexes, extras, scripts, and manual cleanup.

How to migrate from pyright to ty

Evaluate and plan migration from pyright to ty, OpenAI'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

Set, change, upgrade, or downgrade the Python version of a uv project by pinning with `.python-version` and editing `pyproject.toml`.

How to create a pylock.toml lockfile

Generate PEP 751 pylock.toml with uv export, pip lock, or pdm export. Compare producers, pick the right one.

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 uv's default .venv location using UV_PROJECT_ENVIRONMENT environment variable or the --active flag to use an existing virtual environment.

How to distribute internal Python CLI tools with uv

Distribute internal Python CLI tools with uv: install from private index, git repo, or wheel. Pin versions, upgrade teams, bootstrap CI.

How to install from a pylock.toml lockfile with pip

Install locked dependencies with pip 26.1+: `pip install -r pylock.toml --no-deps` for exact lockfile match.

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 lock uv script dependencies for reproducible execution

Use uv lock --script to pin a single-file script's dependencies and uv run --locked to enforce them in CI and shared automation.

How to maintain a uv project

Monthly maintenance checklist: automate Dependabot, uv audit, pre-commit auto-update, then do quarterly manual verification.

How to manage cross-repository Python dependencies with uv

Share packages across repos with uv. Use editable paths for development, git refs for pinning, [tool.uv.sources] to override sources.

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, commit, refresh, and troubleshoot uv.lock so every machine and deployment installs identical dependency versions.

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 for private registries (AWS CodeArtifact, Artifact Registry, Artifactory, Azure). Add indexes, auth, proxies, and TLS certs.

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 Measure Code Coverage with pytest-cov

Measure test coverage with pytest-cov: configure in pyproject.toml, enforce thresholds, report in CI.

How to Parameterize Tests with pytest

pytest.mark.parametrize: run same test logic across multiple inputs with custom IDs, stacked decorators, and indirect fixtures.

How to replace tox with uv and a Makefile

Orchestrate multi-version tests with uv + Makefile, replacing tox. Parallelism via `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 in uv-managed Python projects: filter tests, stop on failure, re-run failures, show output, and set persistent defaults.

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 and django-stubs in a uv project

Set up django-stubs and mypy in uv projects: configure the Django mypy plugin in pyproject.toml for legacy codebase type checking.

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, silence migrations and settings.py, catch Django bugs.

How to Disable Ruff Rules for a Block of Code

Suppress Ruff lint rules across a range of lines with # ruff: disable and # ruff: enable comments, instead of repeating # noqa on every line or ignoring a whole file.

How to Disable the Ruff Formatter for a Block of Code

Stop the Ruff formatter from reformatting a hand-aligned block with # fmt: off and # fmt: on, skip a single statement with # fmt: skip, and keep the comments where they take effect.

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

Sort Python imports with Ruff using the I rule: the one-line command, pre-commit and VS Code setup, and why ruff format leaves imports alone.

How to test a Python library against multiple type checkers

Run mypy, pyright, and Pyrefly against your library's test suite to confirm your public API type-checks correctly for all users, without cluttering source code with checker-specific ignores.

How to try the ty type checker

Install and run ty, OpenAI'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

Host private or mirrored Python packages with devpi, pypiserver, or bandersnatch.

How to Protect Against Python Supply Chain Attacks with uv

Use uv's dependency cooldown to delay newly-published packages and its install-time malware check to block known-malicious versions before they run.

How to Publish a Python Package to conda-forge

Generate a conda recipe with grayskull, submit it to conda-forge staged-recipes, and inherit a bot-maintained feedstock for your PyPI package.

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

Choose Sphinx or MkDocs, scaffold docs, pull docstrings via autodoc/mkdocstrings, preview locally, deploy to Read the Docs.

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 Vet a Python Package Before Installing It

PyPI vetting checklist: download trends, source verification, recent commits, reputation tools.

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 Combine Coverage Across a CI Matrix

Aggregate coverage.py from GitHub Actions matrix jobs into one report, post to run summary, gate with single threshold.

How to deploy a uv project to AWS Fargate

Build a Fargate-ready container image with uv, match its CPU architecture, and cache uv downloads in an ECS build pipeline using Amazon ECR.

How to deploy a uv project to AWS Lambda

Package a uv project for AWS Lambda using container images, zip archives, or layers, with cross-platform builds and faster cold starts.

How to deploy a uv project to Google Cloud Run

Deploy a uv project to Cloud Run two ways: a source deploy that builds with Google's uv buildpack, or a Dockerfile you control. Covers the PORT contract and Secret Manager.

How to Deploy a uv Project to Hugging Face Spaces

Deploy a uv-locked app to Hugging Face Spaces with the Docker SDK: write the Dockerfile for the UID 1000 user, request a GPU, and cache models across restarts.

How to deploy a uv project to Vercel

Vercel runs uv as its default Python installer and reads uv.lock natively. Commit the lockfile, pin the Python version, and keep the function bundle under 500 MB.

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 run uv on Modal

Build Modal images from a uv.lock with uv_sync, install ad-hoc packages with uv_pip_install, and run the synced environment on a GPU.

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...