Python Development Tooling How-To Guides

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

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

Migration

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

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 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-based project to pyproject.toml using uv init and uv add.

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 switch from pyenv to uv for managing Python versions

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

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 the Python version for a uv project by editing pyproject.toml or pinning with .python-version.

How to customize uv's virtual environment location

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

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 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 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 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 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 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 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 Scan Python Dependencies for Vulnerabilities

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

How to Verify Dependencies with Hashes in uv

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

CI, Hooks & Containers

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

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