Python Developer Tooling Handbook – Testing

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:

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 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 tests in parallel with pytest-xdist

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

A large test suite that runs sequentially can take minutes. pytest-xdist distributes tests across multiple worker processes, which can lead to considerable speed ups depending on the test suite and hardware.

Installation

Add pytest-xdist as a dev dependency using uv:

uv add --dev pytest-xdist

Running tests in parallel

Pass -n auto to let pytest-xdist detect the number of available CPU cores and spawn that many workers:

How to Run Tests Using uv

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

If your project lists pytest as a dev dependency, run every test with a single command:

uv run pytest

uv run syncs the virtual environment automatically, so the project and its dependencies are always installed before pytest starts.

How to Test Against Multiple Python Versions Using uv

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

A library that works on Python 3.11 can break on 3.12 because of removed deprecations, C API changes, or subtle differences in standard library behavior. Catching these failures before your users do requires running tests against each version you support. uv makes this straightforward: it downloads Python versions on demand, so there is no need to install them yourself.

Prerequisites

uv installed on your system
A Python project with pytest configured as a dependency (see Setting up testing with pytest and uv)

Run Tests Against a Single Alternate Version

Pass --python to select a specific Python version:

How to use uv to speed up tox

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

tox spends most of its time creating virtual environments and installing dependencies. The tox-uv plugin replaces both pip and virtualenv with uv, cutting that overhead without changing how you write tox.ini or run your test matrix.

Note

nox: Python Test Automation Tool

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

nox manages Python virtual environments and runs tests across multiple Python versions and configurations. Unlike tox, which uses INI format configuration files, nox uses Python files for configuration, providing more flexibility and control. Hatch offers a third approach with its environment matrix system configured in pyproject.toml.

When to Use nox

nox solves the problem of running test suites, linters, and other checks across multiple Python versions and dependency combinations. Choose nox over tox when test automation logic requires conditionals, loops, or dynamic session generation that INI configuration cannot express. Projects with straightforward multi-version testing may find uv’s built-in multi-version support sufficient without a separate tool; see Do you still need tox or nox if you use uv? for guidance.

pytest: Python Testing Framework

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

pytest is a mature, feature-rich testing framework for Python that simplifies test writing and execution through a clear, concise syntax. Unlike Python’s built-in unittest module, pytest minimizes boilerplate and offers powerful fixture capabilities, parameterized testing, and a comprehensive plugin ecosystem.

pytest is the standard choice for most Python testing, from small scripts to large applications. Its assert-based syntax requires less code than unittest, and its fixture system scales well as projects grow. The main reasons to prefer unittest over pytest are maintaining a codebase already committed to unittest conventions or working in an environment where third-party packages are restricted.

Setting up testing with pytest and uv

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

Every Python project needs tests, but setting up a test suite from scratch involves decisions about project layout, dependency management, and configuration. This tutorial walks through the full setup using pytest and uv: creating a project, writing tests, using fixtures, measuring coverage, and configuring defaults.

Prerequisites

Install uv on your system.

Creating a Project with Tests

Start by creating a sample project with a test directory structure:

tox: Python Test Automation Tool

Tim Hopper — Fri, 01 May 2026 06:56:25 -0400

tox is a command-line testing automation tool that manages Python virtual environments and executes tests across multiple Python versions and configurations. It allows developers to define standardized test environments and run tests reliably across different platforms.

tox is particularly valuable for library maintainers who must ensure their packages work correctly across multiple Python versions and dependency configurations.

Key Features

Multi-Environment Testing: Creates and manages separate virtual environments for different Python versions and configurations
Configuration as Code: Declarative test environment setup in tox.toml, pyproject.toml ([tool.tox]), or tox.ini
CI Integration: Commonly used in continuous integration pipelines
Parallel Execution: Can run test environments concurrently with --parallel
Dependency Management: Handles installation of test dependencies per environment
Platform Support: Works across Windows, macOS, and Linux

Configuration Files

tox 4.21 (September 2024) added native TOML configuration. The current tox documentation recommends TOML over INI for new projects, reserving INI for advanced features that the TOML parser does not yet expose. Four file layouts are supported:

tox-uv: uv backend for tox

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

tox-uv is a plugin for tox that replaces pip and virtualenv with uv. When installed alongside tox, it activates automatically and handles all virtual environment creation and dependency installation using uv’s resolver and installer. No changes to tox.ini are required for basic usage.

Installation

The recommended approach installs tox and the plugin together as a uv tool:

uv tool install tox --with tox-uv

Two distribution packages exist:

Python Developer Tooling Handbook – Testing

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

What uv handles on its own

How to Fix Common pytest Errors with uv

ModuleNotFoundError

Missing uv sync

How to replace tox with uv and a Makefile

How to run tests in parallel with pytest-xdist

Installation

Running tests in parallel

How to Run Tests Using uv

How to Test Against Multiple Python Versions Using uv

Prerequisites

Run Tests Against a Single Alternate Version

How to use uv to speed up tox

nox: Python Test Automation Tool

When to Use nox

pytest: Python Testing Framework

Setting up testing with pytest and uv

Prerequisites

Creating a Project with Tests

tox: Python Test Automation Tool

Key Features

Configuration Files

tox-uv: uv backend for tox

Installation

Missing `uv sync`