Python Developer Tooling Handbook – Python Development Tooling How-To Guides

How to add dynamic versioning to uv projects

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Dynamic versioning generates version numbers from Git tags instead of requiring manual updates to a static version string in pyproject.toml. The release workflow becomes a single git tag command: the build backend reads the tag, and the wheel and source distribution filenames pick up the matching version automatically.

This guide uses uv-dynamic-versioning, a hatchling plugin that ships a sensible default configuration for uv projects.

Prerequisites

A Git repository for your Python project with at least one commit
uv installed on your system
A src/your_package/ layout (the default for uv init --package)

Configure the build system

Update pyproject.toml to use uv-dynamic-versioning as a build backend dependency:

How to add Python to your system path with uv

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Since uv 0.8, Python versions installed by uv are automatically added to your PATH. When you run uv python install, uv places versioned Python executables (like python3.12) in a directory on your PATH (typically ~/.local/bin).

Installing a Python version

uv python install 3.12

After running the command, the versioned executable is available:

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

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Pyrefly can turn def total(numbers): into def total(numbers: list[int]) -> int: without running your code. The command is pyrefly infer, previously called autotype, and it writes draft annotations by reading call sites with static analysis.

For a legacy codebase with thousands of unannotated functions, this turns weeks of manual annotation into a reviewable diff. The output needs a human review pass before merging.

Note

How to Build Multi-Platform Wheels with cibuildwheel

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Python packages with compiled extensions (C, C++, Rust, Cython) need platform-specific wheels so users can install them without a compiler. cibuildwheel automates building these wheels across operating systems, architectures, and Python versions in CI.

This guide sets up a GitHub Actions workflow that builds wheels for Linux, macOS, and Windows, then publishes them to PyPI.

Prerequisites

A Python project with a compiled extension and a PEP 517-compliant build backend (setuptools, scikit-build-core, maturin, etc.)
A [build-system] table in pyproject.toml
A GitHub repository
A PyPI account with trusted publishing configured for the repository

Configure cibuildwheel

Add a [tool.cibuildwheel] section to pyproject.toml. This example targets CPython 3.11 through 3.13, skips 32-bit builds, and runs pytest after each wheel build:

How to Build Read the Docs with uv

Tim Hopper — Fri, 01 May 2026 06:58:04 -0400

If your docs already build on Read the Docs, you can now switch .readthedocs.yaml to native uv support instead of maintaining a hand-rolled build.jobs override. Read the Docs added this support on April 21, 2026. The two supported paths are uv sync with a docs dependency group, and uv pip install with a requirements file.

Define a docs dependency group

If your project already has a pyproject.toml, declare a dependency group for the documentation toolchain. Groups are the PEP 735 standard place to keep development-only dependencies out of what your users install:

How to change the Python version of a uv project

Tim Hopper — Tue, 14 Apr 2026 13:37:50 -0400

To change the Python version of a uv project, run uv python pin 3.12 to update .python-version, then uv sync to rebuild the virtual environment against the new interpreter. If you also want to change which versions the project supports, edit requires-python in pyproject.toml and run uv lock && uv sync.

A uv project tracks Python versions in two places: the .python-version file pins the development interpreter (e.g., 3.12), and requires-python in pyproject.toml declares which versions the project supports (e.g., >=3.11). The pinned version must satisfy the requires-python constraint, or uv will report an incompatibility error.

How to configure Claude Code to use uv

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code defaults to pip when it needs to install packages or run scripts. A CLAUDE.md file in your project root overrides that default so every session uses uv instead.

Tip

How to configure Claude Code to use virtual environments

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code starts a fresh shell for every Bash tool call, so source .venv/bin/activate in one command has no effect on the next. Without configuration, Claude reaches for system Python and installs packages outside the project’s virtual environment. Four configuration patterns work around the stateless-shell limitation:

uv run for projects on uv, which sidesteps activation entirely
A CLAUDE.md instruction that tells Claude to call the venv’s interpreter directly
A .claude/settings.json env block that pre-sets VIRTUAL_ENV and PATH for every session
A PreToolUse hook that blocks bare python and pip so the rules are enforced, not just suggested

Trace why `source activate` doesn’t persist

Each Bash tool call Claude Code runs spawns a separate shell process. Environment changes made by source .venv/bin/activate (it sets VIRTUAL_ENV and prepends .venv/bin to PATH) live only inside that shell. When the next tool call starts a new shell, those variables are gone.

How to configure Cursor for a uv project

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

Cursor is a fork of VS Code, so most Python tooling configuration works the same way. The key difference is Cursor’s AI agent, which needs explicit rules to use uv instead of pip. This guide covers both the editor setup and the agent configuration.

How to configure Cursor rules to use uv

Tim Hopper — Wed, 22 Apr 2026 11:52:08 -0400

This guide shows you how to configure Cursor editor rules to automatically use uv for Python package management instead of pip. Cursor rules help ensure consistent tooling across your development workflow by providing context to the AI about your project preferences.

Prerequisites

Cursor editor installed
uv installed on your system
A uv-based Python project (e.g. created with uv init)

Create Cursor rules to use uv

1. Create a global Cursor rules file

To apply uv rules across all your Python projects, create a global Cursor rules file by opening the Cursor Command Palette (View Menu → Command Palette), search for “New Cursor Rule”, and create a new rule named “uv”.

How to configure mypy and django-stubs in a uv project

Tim Hopper — Tue, 05 May 2026 06:56:59 -0400

Run mypy on a Django project without django-stubs and the first error is Need type annotation for "name" on every model field. mypy cannot infer that models.CharField(max_length=200) resolves to str or that Question.objects.filter() returns a QuerySet[Question]. The django-stubs package and its bundled mypy plugin fill those gaps.

This guide installs both with uv and configures everything from a single pyproject.toml, with an override pattern for adopting type checking gradually on a legacy Django codebase.

How to configure mypy strict mode

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

This guide assumes you have a Python project set up with uv and mypy installed as a dev dependency.

Running mypy with default settings is lenient. It skips function bodies that lack type annotations and ignores several categories of type errors. Strict mode closes these gaps by requiring annotations on all functions and enabling a curated set of optional checks. The exact flags included in --strict may change between mypy releases.

How to configure recommended Ruff defaults

Tim Hopper — Tue, 05 May 2026 16:21:56 -0400

This guide assumes you have a Python project set up. If you haven’t created a project yet, see the project creation tutorial before proceeding.

This guide shows how to configure Ruff with a curated set of linting rules that extend beyond the defaults. When starting a new project, it’s easier to enable a comprehensive set of rules from the beginning and selectively disable any that don’t fit the project’s needs, rather than gradually adding rules later when there’s already code to fix.

How to configure Ruff for Django

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

Ruff’s default rule set knows nothing about Django. It will not flag CharField(null=True), but it will flag every long line in an auto-generated migration. This guide fixes that: enable the DJ rule set, give Ruff the per-file ignores Django’s generated code needs, and produce a configuration block that catches Django-specific bugs without burying them under noise.

This guide assumes a working Django project. Follow Set up a Django project with uv first if there isn’t one yet.

How to configure Ruff with Claude Code

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code does not run Ruff by default, so Python edits land unformatted and lint errors slip through unless you wire Ruff in yourself. Out of the box, Claude often calls bare ruff (which may resolve outside the project’s virtual environment) and skips formatting after edits. Wiring Ruff in correctly takes four layers, each with a different job.

This guide covers all four and how they stack together:

A CLAUDE.md instruction that points Claude at Ruff
The Astral plugin’s /astral:ruff skill for on-demand Ruff guidance
A PostToolUse hook that auto-formats every Python edit
A pre-commit gate that catches anything Claude missed before commit time

Prerequisites

Claude Code installed
uv installed
A Python project with Ruff added as a dev dependency (uv add --dev ruff)
jq installed if you want to use the shell version of the auto-format hook

Pick the right layer for your goal

Each layer answers a different question. Pick the ones that match what you actually need; nothing requires installing all four.

How to configure VS Code for a uv project

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

VS Code needs three things to work well with a uv project: the right Python interpreter, a formatter and linter, and a test runner. This guide covers each.

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

Tim Hopper — Tue, 14 Apr 2026 23:55:39 -0400

A standalone Python script paired with a requirements.txt is the old way of saying “this script needs these libraries.” PEP 723 replaces the sidecar file with a TOML block embedded in the script itself, and uv reads that block to install dependencies into a temporary virtual environment on every run.

Translate the requirements.txt into inline metadata

Point uv add --script at the existing requirements file. uv reads it and prepends a PEP 723 block to the script:

How to create a new Python project with Codex

Tim Hopper — Sun, 19 Apr 2026 22:45:37 -0400

Codex produces consistent project scaffolding when you explicitly point it at the Modern Python Project Setup Guide for AI Assistants. Use the canonical Markdown URL (https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants/index.md) inside your first prompt so Codex follows the uv-based workflow on macOS, Linux, and Windows.

Launch Codex with the guide loaded

1. Open a terminal in your repository root

Codex works best when it starts in the directory that already contains your project files (or the Git repo where the project will live). On macOS/Linux you can cd /path/to/repo; on Windows use PowerShell’s Set-Location.

How to Create and Distribute a Python CLI Tool

Tim Hopper — Mon, 20 Apr 2026 08:25:51 -0400

pyproject.toml lets you attach any Python function to an executable command name via [project.scripts]. When someone installs the package, their package manager creates a wrapper script that calls that function. With uvx, users can run the tool without even installing it first.

Tip

How to create and use a Python virtual environment with venv

Tim Hopper — Tue, 21 Apr 2026 08:54:19 -0400

A README says “create a virtual environment” before it tells you what that means. Use Python’s built-in venv module to create one, activate it, and install packages into the right place. For the concepts, see What is a virtual environment?. For a new project from scratch, uv handles all of this for you.

Create the environment

Run this from your project directory:

python3 -m venv .venv

py -m venv .venv

If Windows does not recognize py, use python -m venv .venv instead.

How to customize uv's virtual environment location

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

When working with uv projects, the virtual environment is automatically created in a folder called .venv in your project directory.

your-project/
├── pyproject.toml
├── .venv/          # Virtual environment location
└── src/

You can override this default with a flag or a environmental variable.

How to deploy a uv project to AWS Lambda

Tim Hopper — Tue, 05 May 2026 06:55:50 -0400

AWS Lambda packages a Python function as either a zip archive (up to 250 MB unzipped) or a container image (up to 10 GB). Both formats need every dependency the function imports, compiled for Lambda’s Linux runtime, with no virtual environment and no pip install step at runtime. uv is fast at producing exactly that shape, and its lockfile makes the resulting deployment reproducible.

Pick a packaging format

Format	Pick when
Container image	Production services, dependencies near or above the 250 MB zip limit, native libraries that don’t ship manylinux wheels, image-based local testing.
Zip archive	Small functions, simple dependencies, fastest cold starts on Python managed runtimes.
Lambda layer + zip	Dependencies change rarely, function code changes often.

The zip and layer paths use the same uv export + uv pip install --target recipe; only the zip layout differs. The container path uses Lambda’s official Python base image and uv pip install at build time.

How to distribute internal Python CLI tools with uv

Tim Hopper — Fri, 24 Apr 2026 16:44:14 -0400

Your team built a CLI. Now you need one install path for teammate laptops and fresh CI runners, plus a coordinated way to push updates. uv installs the tool from a private index, a git tag, or a wheel, and uv tool install pkg@latest rolls out upgrades on command.

This guide picks up where How to create and distribute a Python CLI tool leaves off. That page covers publishing the package; this one covers installing it, pinning it, and keeping it current across a team.

How to Enable Ruff Security Rules

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Ruff’s S rule group implements flake8-bandit security checks, catching hardcoded passwords, injection vulnerabilities, insecure hashing, and unsafe deserialization before they reach production.

Enable the Full Set

Add the S group to the project’s pyproject.toml:

[tool.ruff.lint]
extend-select = [
    "S",    # flake8-bandit security rules
]

This enables all flake8-bandit rules at once. Run the linter to see what it finds:

How to fix "No `project` Table Found" error in uv

Tim Hopper — Fri, 10 Apr 2026 07:07:14 -0400

uv project commands (uv run, uv sync, uv add) expect a [project] table in pyproject.toml. Without one, uv reports:

error: No `project` table found in: `/path/to/pyproject.toml`

This happens in two common situations: a repository uses pyproject.toml only for tool configuration (Ruff, Black, mypy) without declaring a project, or a pyproject.toml was created manually and the [project] table was omitted.

How to Fix Common pytest Errors with uv

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

pytest failures that have nothing to do with your actual tests are some of the most frustrating errors in Python development. This guide covers the problems people hit most often when running pytest in uv-managed projects and how to fix them.

ModuleNotFoundError

The most common pytest error in uv projects. There are several causes.

Missing `uv sync`

If you see ModuleNotFoundError for your own package, the project likely has not been installed into the virtual environment:

How to Fix ModuleNotFoundError: No module named 'numpy' During pip Install

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

This guide helps resolve an issue where a Python package fails to install because it cannot find numpy, even though it is already installed in your virtual environment.

Problem

You’re trying to install a Python package using:

uv pip install git+https://github.com/example/examplepkg.git
# or
pip install .

Even though numpy is installed in your environment, the install fails with:

How to fix Python version incompatibility errors in uv

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Understanding the Error

When you see an error like this:

error: The Python request from `.python-version` resolved to Python 3.9.1, which is incompatible with the project's Python requirement: `>=3.10`. Use `uv python pin` to update the `.python-version` file to a compatible version.

This means:

How to fix the "externally-managed-environment" error

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Running pip install on a system Python protected by PEP 668 produces this error:

error: externally-managed-environment

× This environment is externally managed

The fix depends on what was being installed.

Installing project dependencies

Use uv to create a project with its own virtual environment:

How to format pyproject.toml with taplo

Tim Hopper — Mon, 20 Apr 2026 08:05:41 -0400

uv does not include a built-in formatter for pyproject.toml. Taplo is a TOML formatter and validator that keeps pyproject.toml files consistently styled across a project.

Format with uvx

Run taplo as a one-off command without installing it:

uvx taplo fmt pyproject.toml

To check formatting without modifying files (useful in CI):

How to gradually adopt type checking in an existing Python project

Tim Hopper — Sat, 25 Apr 2026 22:02:18 -0400

This guide assumes you have a Python project managed by uv. If you haven’t created a project yet, see the project creation tutorial before proceeding.

Running a type checker on an established codebase for the first time produces hundreds or thousands of errors. That wall of red discourages adoption before it starts. The practical path is to check new code strictly while ignoring legacy issues, then shrink the ignore list over time.

How to Host Your Own Python Package Index

Tim Hopper — Wed, 29 Apr 2026 07:10:45 -0400

A self-hosted Python package index can save a team from PyPI outages, vendor lock-in, or restricted networks, but it also gives that team another service to run. Three tools cover almost every use case: devpi for production multi-team setups, pypiserver for a small team that needs somewhere to put internal-greeter-0.1.0.whl, and bandersnatch for full PyPI mirrors on networks that cannot reach pypi.org.

Hosting an index is the server-side counterpart to How to use private package indexes with uv, which covers the client configuration for managed services like AWS CodeArtifact and JFrog Artifactory.

How to Install bitsandbytes

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

bitsandbytes provides 4-bit and 8-bit quantization for large language models, cutting GPU memory usage enough to run models that would otherwise not fit. Unlike PyTorch (see Why Installing GPU Python Packages Is So Complicated), bitsandbytes publishes platform-specific wheels to PyPI that bundle precompiled CUDA libraries for multiple toolkit versions. A plain pip install works on Linux, Windows, and macOS without extra index URLs.

Requirements

Python >= 3.10
PyTorch >= 2.3 (see How to Install PyTorch with uv)
NVIDIA GPU with compute capability 6.0+ for GPU quantization (Pascal or newer)
NVIDIA driver that supports CUDA 11.8 or later

bitsandbytes also supports CPU-only, AMD ROCm (preview), Intel XPU, and Apple Silicon. GPU quantization requires an NVIDIA GPU.

How to Install DeepSpeed

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

DeepSpeed publishes only a source distribution on PyPI, with no prebuilt wheels. The setup.py requires both PyTorch and a CUDA toolkit to generate metadata, so even a basic install needs CUDA_HOME set and nvcc on PATH. Once installed, individual ops (fused Adam, CPU offloading, transformer kernels) are compiled on first use through PyTorch’s JIT C++ extension system. See Why Installing GPU Python Packages Is So Complicated for background.

Requirements

Platform: Linux (x86_64). Windows has partial support through WSL2. No macOS GPU support.
Software: PyTorch already installed, a C++ compiler (gcc or g++), the CUDA toolkit with nvcc on PATH, and CUDA_HOME set to the toolkit root (e.g. /usr/local/cuda).
System libraries: libaio-dev is required for the async I/O op used by ZeRO-Infinity and NVMe offloading. Install it with apt install libaio-dev on Debian/Ubuntu.

Install from PyPI

DeepSpeed’s setup.py imports torch at the top level, so PyTorch must be present before installation. The --no-build-isolation flag tells the installer to use the current environment’s torch instead of creating a clean build environment:

How to Install Flash-Attention

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

PyPI has no wheels for flash-attn. Every pip install flash-attn triggers a from-source CUDA compilation that can take over two hours (see Why Installing GPU Python Packages Is So Complicated for background). Prebuilt wheels do exist on GitHub Releases, and the package’s setup.py can fetch them automatically if your environment matches.

Requirements

Platform: Linux on NVIDIA Ampere (A100, RTX 3090), Ada Lovelace (RTX 4090), or Hopper (H100). Windows has experimental support since v2.3.2. No macOS support.
Software: CUDA toolkit >=12.0 with nvcc on PATH, PyTorch >=2.2 already installed in the target environment.

Install with prebuilt wheels (recommended)

The flash-attn package includes a CachedWheelsCommand in its setup.py that tries to download a matching prebuilt wheel from GitHub Releases before falling back to compilation. The --no-build-isolation flag is required because setup.py imports torch and packaging at the top level. Both must be installed in the environment before running the install:

How to install from a pylock.toml lockfile with pip

Tim Hopper — Tue, 28 Apr 2026 08:47:02 -0400

A teammate hands you a pylock.toml. Or uv’s uv export --format pylock.toml produces one. Now you need pip to install from it. As of pip 26.1 (April 2026), pip install -r pylock.toml works, with a few caveats worth knowing before you put it in CI.

Confirm pip 26.1 or newer

The -r pylock.toml form was added in pip 26.1. Older pips will treat the file as a regular requirements file and choke on the first TOML line.

How to Install llama-cpp-python

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

PyPI has no prebuilt wheels for llama-cpp-python. A bare pip install downloads a source distribution and compiles it without GPU support, which means inference runs entirely on CPU. To get CUDA or Metal acceleration, the build needs specific CMake flags passed through environment variables, or the install must pull from a separate wheel index that the maintainer publishes.

Requirements

A C/C++ compiler and CMake are required for building from source. The project’s build system expects clang; on systems where only gcc is available, install clang as well (e.g., apt install clang). On macOS, Xcode command-line tools provide both. On Windows, Visual Studio Build Tools with the “Desktop development with C++” workload are needed.

How to install Python CLI tools without Python

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

uvx.sh provides installation scripts for any Python tool on PyPI. Use it to install tools like ruff, pre-commit, or pytest without having uv or Python already installed.

Installing a Tool

Replace {package} with any PyPI package name:

How to install Python with uv

Tim Hopper — Mon, 04 May 2026 08:01:44 -0400

uv downloads and installs Python interpreters on demand, so you usually don’t need to install Python explicitly. Run uv python install ahead of time to make a version available offline or to put it on your PATH. uv pulls prebuilt CPython binaries from python-build-standalone, so installs don’t need admin privileges and don’t replace system Python or interpreters managed by Homebrew or pyenv.

The same commands work on macOS, Linux, and Windows. You only need uv installed first.

How to Install PyTorch with uv

Tim Hopper — Thu, 16 Apr 2026 07:09:14 -0400

PyTorch publishes different wheel builds for CPU, CUDA, ROCm, and XPU on separate package indexes (see Why Installing GPU Python Packages Is So Complicated for background). Getting the right build requires telling uv which index to use.

Default behavior without configuration

Running uv add torch torchvision with no extra configuration installs from PyPI. PyPI carries CPU-only wheels for Windows and macOS, and CUDA 12.8 wheels for Linux (as of PyTorch 2.9.1). For projects that only need CPU support on Windows/macOS and GPU support on Linux, this default works without any additional setup.

How to Install RAPIDS with uv

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

RAPIDS packages live on NVIDIA’s own package index, not PyPI (see Why Installing GPU Python Packages Is So Complicated for background). Getting uv to find them requires registering that index.

Prerequisites

RAPIDS requires:

Linux with glibc >= 2.28 (Ubuntu 20.04+, Debian 10+, Fedora 29+). On Windows, use WSL2 on Windows 11. macOS is not supported.
NVIDIA GPU with compute capability 7.0+ (Volta architecture or newer).
NVIDIA driver version 525.60.13+ for CUDA 12, or 580.65.06+ for CUDA 13.
Python 3.10, 3.11, 3.12, or 3.13.

Check the installed driver version with:

How to install the Astral plugins for Claude Code

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Astral publishes an official Claude Code plugin that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Prerequisites

Claude Code installed
uv installed (required by the ty language server)

Install the plugin for yourself

1. Add the Astral marketplace

Run this slash command inside Claude Code:

How to Install Triton

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Triton is OpenAI’s open-source compiler for writing GPU kernels in Python. Most users encounter it as a transitive dependency of PyTorch, but it can also be installed standalone for custom kernel development. Triton only ships wheels for Linux (x86_64 and aarch64). There are no macOS or Windows builds.

Requirements

Linux (x86_64 or aarch64). Triton has no wheels for macOS or Windows.
Python 3.10 or later (up to 3.14).
glibc 2.27 or later (Ubuntu 18.04+, Debian 10+, RHEL 8+).
An NVIDIA or AMD GPU with appropriate drivers for running compiled kernels. Triton itself installs without a GPU, but kernels cannot execute without one.

Install as a PyTorch dependency (automatic)

PyTorch declares Triton as a dependency on Linux x86_64. Installing PyTorch pulls in the matching Triton version automatically:

How to install uv

Tim Hopper — Fri, 24 Apr 2026 10:27:15 -0400

You can install uv, the fast Python package and project manager, with a standalone installer, with pip, or with package managers like Homebrew, WinGet, and Scoop. The recommended method on every platform is the official standalone installer, because it requires no existing Python interpreter, no package manager, and no other prerequisites.

You do not need Python installed first. The standalone installer downloads a self-contained uv binary, and uv can then install and manage Python interpreters for you.

How to install uv on Linux

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

uv is a fast Python package and project manager. This guide covers how to install it on Linux.

Standalone installer (recommended)

The standalone installer is the recommended method because it requires no prerequisites: no Python, no package manager, nothing. It downloads a prebuilt binary and adds it to your PATH.

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

If your system doesn’t have curl, use wget instead:

How to install uv on macOS

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

uv is a fast Python package and project manager. This guide covers how to install it on macOS.

Standalone installer (recommended)

The standalone installer is the recommended method because it requires no prerequisites: no Python, no package manager, nothing. It downloads a prebuilt binary and adds it to your PATH.

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

After running the installer, open a new terminal window so the updated PATH takes effect.

How to install uv on Windows

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

uv is a fast Python package and project manager. This guide covers how to install it on Windows.

Standalone installer (recommended)

The standalone installer is the recommended method because it requires no prerequisites: no Python, no package manager, nothing. It downloads a prebuilt binary and adds it to your PATH.

Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

The -ExecutionPolicy ByPass flag allows running the installation script from the internet.

How to Install xformers

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

xformers ships prebuilt wheels through the PyTorch package index, not PyPI. Like PyTorch itself, the correct binary depends on the CUDA version of the target machine (see Why Installing GPU Python Packages Is So Complicated for background). Each xformers release is pinned to a specific PyTorch version, so a version mismatch between the two is the most common source of installation failures.

Requirements

Linux (manylinux_2_28, e.g. Ubuntu 20.04+) or Windows. macOS is not supported.
NVIDIA GPU with compute capability 8.0+ (Ampere or newer). V100 support was dropped in xformers 0.0.30.
NVIDIA driver compatible with the target CUDA version.
Python 3.9 or later.

Version compatibility

Each xformers release requires a specific PyTorch version. Installing the wrong combination produces import errors or silent correctness bugs.

How to keep Python up to date with uv python upgrade

Tim Hopper — Sat, 25 Apr 2026 09:07:23 -0400

Run uv python upgrade to pull the latest patch release for every Python that uv manages. Pass a minor version (uv python upgrade 3.12) to scope the upgrade to one line. Virtual environments created from a minor-version pin follow the new patch automatically.

This keeps uv-managed CPython installs current with security and bug-fix releases. It does not touch system Python or interpreters installed by Homebrew or pyenv. For installing a new minor version or switching a project, see how to install Python with uv and how to change the Python version of a uv project.

How to manage cross-repository Python dependencies with uv

Tim Hopper — Wed, 15 Apr 2026 21:34:41 -0400

A uv workspace keeps sibling packages in sync when they live in the same repository. When the packages live in separate repositories, reach for [tool.uv.sources] instead. A source override lets each consumer point a dependency at a local checkout, a git ref, or the published version on PyPI without changing the dependency spec itself.

Note

Python Developer Tooling Handbook – Python Development Tooling How-To Guides

How to add dynamic versioning to uv projects

Prerequisites

Configure the build system

How to add Python to your system path with uv

Installing a Python version

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

How to Build Multi-Platform Wheels with cibuildwheel

Prerequisites

Configure cibuildwheel

How to Build Read the Docs with uv

Define a docs dependency group

How to change the Python version of a uv project

How to configure Claude Code to use uv

How to configure Claude Code to use virtual environments

Trace why source activate doesn’t persist

How to configure Cursor for a uv project

How to configure Cursor rules to use uv

Prerequisites

Create Cursor rules to use uv

1. Create a global Cursor rules file

How to configure mypy and django-stubs in a uv project

How to configure mypy strict mode

How to configure recommended Ruff defaults

How to configure Ruff for Django

How to configure Ruff with Claude Code

Prerequisites

Pick the right layer for your goal

How to configure VS Code for a uv project

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

Translate the requirements.txt into inline metadata

How to create a new Python project with Codex

Launch Codex with the guide loaded

1. Open a terminal in your repository root

How to Create and Distribute a Python CLI Tool

How to create and use a Python virtual environment with venv

Create the environment

How to customize uv's virtual environment location

How to deploy a uv project to AWS Lambda

Pick a packaging format

How to distribute internal Python CLI tools with uv

How to Enable Ruff Security Rules

Enable the Full Set

How to fix "No `project` Table Found" error in uv

How to Fix Common pytest Errors with uv

ModuleNotFoundError

Missing uv sync

How to Fix ModuleNotFoundError: No module named 'numpy' During pip Install

Problem

How to fix Python version incompatibility errors in uv

Understanding the Error

How to fix the "externally-managed-environment" error

Installing project dependencies

How to format pyproject.toml with taplo

Format with uvx

How to gradually adopt type checking in an existing Python project

How to Host Your Own Python Package Index

How to Install bitsandbytes

Requirements

How to Install DeepSpeed

Requirements

Install from PyPI

How to Install Flash-Attention

Requirements

Install with prebuilt wheels (recommended)

How to install from a pylock.toml lockfile with pip

Confirm pip 26.1 or newer

How to Install llama-cpp-python

Requirements

How to install Python CLI tools without Python

Installing a Tool

How to install Python with uv

How to Install PyTorch with uv

Default behavior without configuration

How to Install RAPIDS with uv

Prerequisites

How to install the Astral plugins for Claude Code

Prerequisites

Install the plugin for yourself

1. Add the Astral marketplace

Trace why `source activate` doesn’t persist

Missing `uv sync`