Python Developer Tooling Handbook – uv

uv: A Complete Guide to Python's Fastest Package Manager

Tim Hopper — Fri, 08 May 2026 18:28:09 -0400

uv replaces a half-dozen traditional Python tools with a single binary: interpreter installation, virtual environments, dependency management, version locking, CLI tools, and code formatting. In benchmarks, it creates virtual environments 50x faster than python -m venv and installs packages 5-40x faster than pip depending on cache state.

Note

Build a Python library with a C extension

Tim Hopper — Wed, 29 Apr 2026 07:06:23 -0400

Python handles strings well. C handles them faster. In this tutorial, you’ll write three string functions in C, compile them into a shared library, and call them from Python using cffi. The result is a normal Python package that anyone can import.

Prerequisites

You need two things installed:

uv (installation guide)
A C compiler

Most macOS and Linux systems already have a C compiler. Check by running:

Build a Python library with a C++ extension

Tim Hopper — Fri, 08 May 2026 03:18:44 -0400

Python handles most tasks well, but numerical code and tight loops can hit its performance ceiling. C++ removes that ceiling. This tutorial walks you through creating a Python package where the performance-critical code lives in C++, compiled into a native extension module that Python imports like any other module.

You’ll use three tools together:

uv manages the Python project, dependencies, and virtual environment
scikit-build-core is the build backend that drives CMake to compile C++ code into a Python extension module
pybind11 is the C++ library that bridges C++ and Python, letting you write C++ functions callable from Python

Prerequisites

uv installed (installation guide)
A C++ compiler (g++ or clang++)
CMake 3.15 or later

Most macOS and Linux systems ship with a C++ compiler. On macOS, install the Xcode Command Line Tools (xcode-select --install). On Ubuntu/Debian, install the build-essential and cmake packages.

Build a Python library with a Rust extension

Tim Hopper — Fri, 15 May 2026 11:45:25 -0400

Python is flexible and productive, but sometimes a function needs to run faster than Python allows. Rust gives you that speed with memory safety and no garbage collector. This tutorial walks you through creating a Python package where the performance-critical code lives in Rust, compiled into a native extension module that Python imports like any other module.

You’ll use three tools together:

uv manages the Python project, dependencies, and virtual environment
maturin is the build backend that compiles Rust code into a Python extension module
PyO3 is the Rust library that bridges Rust and Python, letting you write Rust functions callable from Python

Prerequisites

uv installed (installation guide)
Rust installed via rustup

Verify both are working:

Can you trust uv long-term?

Tim Hopper — Tue, 28 Apr 2026 16:07:27 -0400

In March 2026, OpenAI acquired Astral, the venture-backed startup behind uv. Before betting a team’s workflow on a tool whose owner’s priorities just changed, the reasonable question is what happens if Astral’s output slows or stops.

The handbook recommends uv. This page lays out why that recommendation survives the trust question, what would have to change before it doesn’t, and what to do today to keep your migration costs low.

Look at what you actually adopt

uv is dual-licensed under Apache 2.0 and MIT. That license cannot be revoked. Every release that has shipped is permanently available to fork, modify, or redistribute. Anyone, including you, can freeze the source tree at any commit and keep using it. No future owner can take that away.

Create your first Python project with uv

Tim Hopper — Fri, 15 May 2026 07:00:57 -0400

This Python uv tutorial walks you through building a text analysis tool that counts words, measures sentence length, and reports word frequency. No prior Python experience required; uv handles the Python install, project scaffolding, and dependency management for you.

Prerequisites

Before we begin, make sure you have uv installed on your system. You can install it following the directions from the uv documentation.

Git is optional. uv does not install Git for you, but if Git is already on your PATH, uv init initializes a Git repository in the new project. The tutorial works either way.

Do I need a project to use uv?

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

If your Python life is a folder full of short scripts that glue APIs together and rename files, uv’s first move can look like overkill: uv init, then a pyproject.toml. uv works fine for scripts, but it assumes a different mental model from the pip install habit most script authors carry, and forcing the old habit onto uv is where people get stuck.

The short answer: no, you don’t need a project. You have four options, and the right one depends on what the script is.

Do you still need tox or nox if you use uv?

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

For many projects, no. uv can run your test suite against multiple Python versions without any extra tool. But tox and nox do more than version switching, and the gap between “run pytest on 3.12” and “test five Python versions against two dependency sets in parallel” is where they still matter.

What uv handles on its own

uv run --python selects a Python version and executes a command in your project’s environment. If that version is not installed, uv downloads it automatically:

Getting started with uv

Tim Hopper — Thu, 14 May 2026 08:14:46 -0400

uv handles Python installation, project setup, dependency management, and script execution in a single tool. This tutorial walks through each of those capabilities so you can start using uv for any Python project.

Prerequisites

You need a terminal (Terminal on macOS, PowerShell on Windows, or any Linux shell). No prior Python installation is required.

Git is optional. If Git is on your PATH, uv init initializes a repository in the new project. uv does not install Git itself; install it separately if you want version control. The tutorial steps work either way.

How do pyenv and uv compare for Python interpreter management?

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

pyenv manages Python versions and gets out of the way; uv manages Python versions as part of controlling your entire workflow. That difference in scope shapes every other trade-off between the two tools.

Design Philosophy

pyenv

pyenv embodies the Unix principle of “do one thing well.” Its sole purpose is managing Python interpreter installations and version switching. This focused approach means pyenv integrates seamlessly with existing workflows; after selecting a Python version, developers use familiar tools like pip and venv for package management and virtual environments.

How do uv and Poetry compare?

Tim Hopper — Fri, 10 Apr 2026 13:36:01 -0400

Poetry and uv both manage Python projects through pyproject.toml, create lockfiles, and handle virtual environments. Poetry has been the default recommendation for years; uv, built by Astral, arrived in 2024 with broader scope and faster dependency resolution. They differ in how.

Scope

Poetry handles dependency management, virtual environments, building, and publishing. Everything else it delegates. A different Python version requires pyenv. Running a CLI tool without installing it globally requires pipx.

How Python tools adopt uv under the hood

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

You don’t have to switch to uv to get uv’s speed. Pixi, Hatch, PDM, and tox now use uv’s resolver and installer as their backend, which means your existing tool may already run on uv under the hood.

Which tools use uv

Tool	What it delegates to uv	How to enable
Pixi	PyPI dependency resolution and installation	Automatic (default behavior)
Hatch	Dependency installation and venv creation	`installer = "uv"` in env config
PDM	Dependency resolution and installation	`pdm config use_uv true` (experimental)
tox (via tox-uv)	Dependency installation and venv creation	Install the `tox-uv` plugin
nox	Dependency installation	Enable nox’s uv backend
prek	Python version and venv management for hooks	Automatic

Pixi uses uv by default for all PyPI packages. Prek does the same for hook environments. The rest require opt-in configuration.

How to add dynamic versioning to uv projects

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 Build Read the Docs with uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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, 13 May 2026 06:43:22 -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 Cursor for a uv project

Tim Hopper — Wed, 13 May 2026 06:43:22 -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, 13 May 2026 06:43:22 -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 VS Code for a uv project

Tim Hopper — Tue, 12 May 2026 07:33:09 -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 — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 customize uv's virtual environment location

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 fix "No `project` Table Found" error in uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 Python version incompatibility errors in uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 install Python CLI tools without Python

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 — Wed, 13 May 2026 06:43:22 -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 — Sat, 16 May 2026 07:30:29 -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 uv

Tim Hopper — Mon, 11 May 2026 06:31: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 32-bit Raspberry Pi OS

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

uv’s standalone installer works on 32-bit Raspberry Pi OS (armv7l), but three quirks bite first-time users: uv python install can fail to detect glibc on some Pi setups, PyPI rarely ships armv7l wheels, and a 32-bit userland running on a 64-bit kernel reports the wrong architecture. This guide walks through each so a 32-bit Pi install ends up in a working state.

For 64-bit Pi OS, the standard path applies; see How to run Python scripts on a Raspberry Pi with uv.

How to install uv on Linux

Tim Hopper — Wed, 13 May 2026 06:43:22 -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 — Thu, 14 May 2026 14:35:17 -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 — Wed, 13 May 2026 06:43:22 -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 keep Python up to date with uv python upgrade

Tim Hopper — Wed, 13 May 2026 06:43:22 -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, 13 May 2026 06:43:22 -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

How to migrate from Pipenv to uv

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

Pipenv combines pip and virtualenv into a single tool. uv covers the same ground and adds Python version management, a standards-compliant pyproject.toml-based workflow, and significantly faster dependency resolution.

Migrating replaces the Pipfile and Pipfile.lock with pyproject.toml and uv.lock, and swaps pipenv commands for their uv equivalents.

Automated migration

The migrate-to-uv tool automates the conversion.

1. Run the migration tool

$ uvx migrate-to-uv

The tool reads your Pipfile and:

How to migrate from Poetry to uv

Tim Hopper — Thu, 14 May 2026 14:35:17 -0400

This guide walks through the process of migrating a Poetry-managed Python project to uv using the migrate-to-uv tool.

Prerequisites

uv installed
A Poetry-managed Python project

Basic Migration

1. Navigate to your Poetry project directory

cd your-poetry-project

2. Run the migration tool

uvx migrate-to-uv

The tool will:

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

Tim Hopper — Mon, 04 May 2026 08:09:53 -0400

To migrate a requirements.txt project to pyproject.toml, run uv init --bare to create a minimal pyproject.toml, then uv add -r requirements.txt to import every dependency. uv reads the file, writes the packages into [project.dependencies], and generates a uv.lock file that pins exact resolved versions.

For a detailed explanation of why pyproject.toml replaces requirements.txt, see why choose pyproject.toml over requirements.txt.

Prerequisites

Install uv if it isn’t already on your system.

How to migrate from uv to pip

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

Moving a uv-managed project to pip is mostly an audit of pyproject.toml, not a rebuild of the project. uv consolidates Python interpreter installs, virtual environments, resolution, package installation, and lockfile generation into one tool, but if a project’s metadata sticks to packaging standards, most of the substitutes are short. This how-to walks through the audit and the runtime equivalents: pyenv on macOS and Linux, the official python.org installer on Windows.

Audit your pyproject.toml for uv-specific tables

Before exporting a lockfile, scan your pyproject.toml for settings under [tool.uv] and tables under [tool.uv.*]. Anything outside that namespace is already standardized and pip can read it. The settings that matter:

How to Protect Against Python Supply Chain Attacks with uv

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

Malicious packages uploaded to PyPI are usually caught and yanked within hours or days. A dependency cooldown tells uv to ignore packages published within a recent window, so compromised versions get removed before they ever reach your environment.

Set a dependency cooldown

The exclude-newer setting accepts durations and timestamps. For security hardening, durations are the right choice because they create a rolling window that moves forward with the current date.

How to Publish to TestPyPI with uv

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

PyPI versions are write-once. Upload 0.1.0 with a broken README or a missing dependency, and the only fix is a new version number. TestPyPI is a parallel index wired to the same tooling where the cost of a bad upload is zero. Upload there first and promote to PyPI only after the rehearsal works end to end.

This guide uses uv for the build, upload, and verification steps. The workflow slots into the trusted-publishing setup for CI or runs entirely from a local shell with an API token.

How to replace tox with uv and a Makefile

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

A Makefile is already the control surface for many Python projects. make test, make lint, make format are muscle memory. Adopting tox on top means learning a second config format with its own INI DSL, its own matrix syntax, and its own per-environment caching story, just to loop pytest across Python versions.

uv makes that loop possible inside Make itself. Four pattern rules cover what most teams use tox for. The one piece that turns “works but slow” into a genuine tox replacement is uv’s UV_PROJECT_ENVIRONMENT variable, which lets each Python version keep its own virtual environment side by side instead of rebuilding .venv on every switch. This guide builds the Makefile from scratch, then shows where it stops being the right tool and tox-uv or nox takes over.

How to Run a Jupyter Notebook with uv

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

When working with Jupyter notebooks, you should run them in isolated environments to prevent dependency conflicts. uv provides several streamlined ways to do this.

Using Jupyter with uv’s Isolated Environments

To launch a Jupyter notebook with specific dependencies using uv:

uv run --with jupyter --with pandas --with matplotlib jupyter lab

This single command:

How to Run a Python REPL with uv

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

uv does not currently officially support a system-level installation of Python, however, you can try it in preview mode.

To start an interactive Python REPL (Read-Eval-Print Loop) session using uv:

Python Developer Tooling Handbook – uv

uv: A Complete Guide to Python's Fastest Package Manager

Build a Python library with a C extension

Prerequisites

Build a Python library with a C++ extension

Prerequisites

Build a Python library with a Rust extension

Prerequisites

Can you trust uv long-term?

Look at what you actually adopt

Create your first Python project with uv

Prerequisites

Do I need a project to use uv?

Do you still need tox or nox if you use uv?

What uv handles on its own

Getting started with uv

Prerequisites

How do pyenv and uv compare for Python interpreter management?

Design Philosophy

pyenv

How do uv and Poetry compare?

Scope

How Python tools adopt uv under the hood

Which tools use uv

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 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 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 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 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 fix "No `project` Table Found" error in uv

How to Fix Common pytest Errors with uv

ModuleNotFoundError

Missing uv sync

How to fix Python version incompatibility errors in uv

Understanding the Error

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

How to install uv

How to install uv on 32-bit Raspberry Pi OS

How to install uv on Linux

Standalone installer (recommended)

How to install uv on macOS

Standalone installer (recommended)

How to install uv on Windows

Standalone installer (recommended)

How to keep Python up to date with uv python upgrade

How to manage cross-repository Python dependencies with uv

How to migrate from Pipenv to uv

Automated migration

1. Run the migration tool

How to migrate from Poetry to uv

Missing `uv sync`