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

Add uv-installed Python versions to your system PATH. Access multiple Python versions system-wide without virtual environments.

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 from a prebuilt wheel in seconds instead of waiting hours for a CUDA compile.

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 (and Which Method to Choose)

Install Python with uv on macOS, Windows, or Linux, and let one tool manage versions so every project gets the right one.

How to install Python CLI tools without Python

Install any Python CLI tool (ruff, pytest, pre-commit) from PyPI without Python or uv using uvx.sh one-liners on macOS, Linux, or Windows.

How to Install Python on macOS

Install Python on macOS with uv instead of the system python3 or Homebrew, so pip stops failing and versions stay current.

How to Install Python on Windows

Install Python on Windows with uv or python.org. Stop the Microsoft Store from hijacking python and get a real interpreter on your PATH for development.

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 Triton GPU compiler for custom kernel development on Linux. Works standalone or as a PyTorch dependency for GPU optimization.

How to install uv

Install the uv package manager on macOS, Linux, or Windows. Which installation method to choose and troubleshooting.

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 with the standalone installer, Homebrew, or pip. Fast Python package manager with zero prerequisites.

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 via PowerShell, WinGet, or Scoop. Fast Python package manager ready for development.

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 for local LLM serving and inference. NVIDIA CUDA GPU acceleration. OpenAI-compatible API endpoints.

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 with hooks. Agents fix violations immediately using the same rules that gate your commits.

How to configure Claude Code to run your pytest suite

Wire pytest into Claude Code with Stop hooks for fast feedback. Sparse tracebacks help agents fix failures efficiently.

How to configure Claude Code to use uv

Configure Claude Code to use uv without approval prompts. Set rules in CLAUDE.md and allow uv commands in .claude/settings.json.

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

Configure Cursor to use uv instead of pip. Let the AI agent install packages correctly with uv add and uv run.

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

Configure VS Code for uv projects: auto-detect the .venv interpreter, enable Ruff formatting, and run pytest without extra setup.

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

Scaffold Python projects with Codex. Pipe the Modern Python Setup Guide URL and let Codex bootstrap the project.

How to install OpenAI's Astral plugins for Claude Code

Install OpenAI's Astral plugin for Claude Code. Get skills and a language server for uv, ruff, and ty with live type diagnostics.

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

Create reusable Claude Code skills to automate Python workflows. Write once, invoke by slash command or natural language description.

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 conda to uv

Convert a conda environment to a uv project with pyproject.toml and uv.lock for reproducible installs that finish in seconds.

How to migrate from mypy to Pyrefly

Migrate from mypy to Pyrefly. Auto-convert config, handle stricter diagnostics with baselines, iterate on CI.

How to migrate from mypy to ty

Should you switch from mypy to ty? When ty fits, when to wait, and how to map your mypy config to ty.

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 from Poetry to uv: convert pyproject.toml, regenerate lockfiles, and update scripts and indexes.

How to migrate from pyright to ty

Migrate from pyright to ty. Get faster type checking with no Node.js dependency and significantly simpler CI.

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

Convert requirements.txt to pyproject.toml with uv. Import pins, generate lockfiles, and keep reproducibility.

How to migrate from setup.py to pyproject.toml

Migrate from setup.py to pyproject.toml. Move to the modern standard, drop setuptools complexity, and unlock uv builds.

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

Switch from pyenv to uv for Python version management. Faster, integrated workflows. Compatible with .python-version files.

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

Map pip, venv, pyenv, pip-tools, and pipx commands to uv equivalents. Migrate to uv's faster, simpler dependency management effortlessly.

Daily Workflow

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

How to Add a Dependency to a uv Project

Add a package to a uv project with uv add: it records the dependency in pyproject.toml and the lockfile so anyone who runs uv sync gets the same versions.

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

Create and activate a Python virtual environment with venv on macOS, Linux, and Windows. Includes activation syntax and troubleshooting.

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

Run Jupyter with uv in isolated environments. One command to launch, reproduce setups, or add packages without project conflicts.

How to Run a Python REPL with uv

Start an interactive Python REPL with uv. Run with specific Python versions, add temporary packages, or skip project dependencies.

How to Run Parallel AI Coding Agents on One Python Project

Run multiple AI coding agents in parallel with git worktrees and isolated uv environments. Agents edit independently without conflicts.

How to run the IPython shell in your uv project

Run IPython in a uv project without modifying dependencies. Temporary sessions with --with or permanent dev dependency setup.

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 a Dependency Past Its Version Ceiling

Raise the version ceiling in pyproject.toml and force uv to re-lock so a capped dependency can move to its new major.

How to Upgrade Python Developer Tools

Stay current on Python developer tools: the right upgrade command depends on how each tool was installed.

How to upgrade uv

Upgrade uv to the latest version. Get bug fixes and new features without downtime using uv self update or your package manager.

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

Set uv's --exclude-newer to a date or a duration to rebuild an old environment exactly or keep brand-new releases out of a resolution.

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 marimo with uv

Run marimo notebooks with uv: sandboxed PEP 723 notebooks, ad-hoc uvx sessions, and project environments.

How to use pip in a uv virtual environment

Add pip to a uv virtual environment. Support Jupyter %pip magic and tools that 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. Define all development commands in pyproject.toml.

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 as its installer. Speed up environment creation 5-10x without changing Hatch workflows.

How to use uv to speed up PDM

Configure PDM to use uv as its resolver. Speed up dependency resolution 5-10x without changing your PDM workflow.

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

Write self-contained scripts with PEP 723 metadata. Declare dependencies inline and run with `uv run` without a project.

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

Replace tox with uv and Make for faster multi-Python testing. Parallel test runs with minimal configuration overhead.

How to run tests in parallel with pytest-xdist

Run pytest tests in parallel across CPU cores with pytest-xdist. Reduce test suite runtime by distributing tests to worker processes automatically.

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

Test against Python 3.10–3.14 with one command via uv. Automatic interpreter downloads mean no manual version management.

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 10-100x 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

Add type annotations with pyrefly infer. Automatically generate parameter and return types from code.

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

Set up Ruff with recommended linting rules from day one. Catch logical errors, modernize syntax, and enforce idiomatic patterns automatically.

How to configure Ruff for Django

Configure Ruff for Django: enable DJ rules to catch null=True on strings and missing __str__, silence auto-generated migrations with per-file ignores.

How to Disable Ruff Rules for a Block of Code

Suppress Ruff rules across a code block with # ruff: disable and # ruff: enable comments. Cleaner than sprinkling # noqa across every line.

How to Disable the Ruff Formatter for a Block of Code

Skip Ruff formatting with # fmt: off and # fmt: on markers. Useful for hand-aligned code that auto-formatting breaks.

How to Enable Ruff Security Rules

Enable Ruff's security rules (flake8-bandit) to catch hardcoded secrets, SQL injection, and weak hashes in your code.

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 Format Python Code Blocks in Markdown Files

Format Python code blocks in Markdown with Ruff 0.16, keep README and docs samples consistent with your source, and stop unwanted rewrites.

How to gradually adopt type checking in an existing Python project

Add type checking to legacy Python code without fixing every error first. Type-check new code strictly while silencing legacy modules.

How to sort Python imports with Ruff

Sort Python imports with Ruff in one command. VS Code organize-on-save, pre-commit hooks, and why ruff format skips imports.

How to test a Python library against multiple type checkers

Test your library against mypy, Pyright, and Pyrefly to catch type errors across all common checkers before release.

How to try the ty type checker

Try ty, OpenAI's fast Python type checker. Install, run against your code with uv, and set up language server support in VS Code or your editor.

How to Type-Check a Django Project with Pyrefly

Type-check a Django project with Pyrefly: install django-stubs, run the checker, and suppress unresolved errors.

Packaging & Publishing

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

How to add dynamic versioning to uv projects

Auto-generate package versions from Git tags with uv. Stop manual version bumps: tag a commit and the wheel version updates automatically.

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. Choose between devpi, pypiserver, or bandersnatch for your network.

How to Ignore a Dependency in Dependabot Without Blocking Its Security Updates

Scope a Dependabot ignore rule to version updates so a pinned package stops routine PRs but still gets security fixes.

How to Keep a Capped Dependency from Blocking Dependabot Security Updates

Drop or raise a version ceiling in pyproject.toml so Dependabot can open security PRs instead of failing silently.

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

Publish to PyPI securely with trusted publishing. Replace API tokens with OIDC for GitHub Actions workflows.

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

Scan Python dependencies for vulnerabilities with uv audit. Catch CVEs before they reach production.

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 uv dependencies with SHA-256 hashes. Detect tampering and cache corruption at install time to block compromised packages.

How to Vet a Python Package Before Installing It

Vet Python packages with a checklist: download trends, source verification, and reputation tools. Catch supply chain risks before they happen.

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 Read the Docs to install dependencies with uv. Use dependency groups and lockfiles for reproducible builds.

How to Cache uvx Tools in GitHub Actions

Stop uvx from re-downloading CLI tools on every CI run by keying the setup-uv cache to a pinned date instead of a lockfile.

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 Azure Container Apps

Deploy a uv project to Azure Container Apps with buildpacks or Dockerfile. Cover zero-to-production quickly.

How to deploy a uv project to Fly.io

Deploy a uv-managed Python web app to Fly.io: a uv Dockerfile, binding to the port Fly routes to, fly launch, machine auto-stop, and secrets.

How to deploy a uv project to Google Cloud Run

Deploy a uv project to Cloud Run via source builds or a custom Dockerfile. Handle PORT and secrets management.

How to Deploy a uv Project to Hugging Face Spaces

Deploy a uv project to Hugging Face Spaces for a free, public app. Handles gradio integration and secrets.

How to deploy a uv project to Vercel

Deploy a uv project to Vercel with zero configuration. Vercel reads uv.lock natively for reproducible Python function installs.

How to Install CUDA PyTorch Wheels Without a GPU

Declare the target CUDA driver version so uv resolves GPU PyTorch wheels on a build machine that has no GPU installed.

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

Put a Python project on GitHub: init Git, commit, create a remote, and push. Includes .gitignore setup and authentication.

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 on Git commits. Includes Ruff, mypy, and ty integration.

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 Docker images with uv for 10x faster builds. Layer caching and reproducible installs with uv.lock in containers.

Troubleshooting

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

Please submit corrections and feedback...