uv-matrix
A small matrix task runner for Python projects using Astral uv.
Warning
Status: early development
uv-matrix runs the same project tasks across Python versions, dependency variants, extras, dependency groups, and arbitrary task variants defined in pyproject.toml:
[tool.uv-matrix.matrix.test] # a matrix named "test"
python-version = ["3.12", "3.13"] # run the job on Python 3.12 and 3.13
tasks = ["run_test"] # run the "run_test" task in every cell
[tool.uv-matrix.tasks.run_test] # a task named "run_test"
run = "pytest" # command run through `uv run`
Why uv-matrix?
Many Python projects need to run checks like this:
run tests against multiple Python versions
run tests with different optional dependencies
run lint, docs, and test tasks from one project configuration
pass the same matrix setup to local development and CI
How it relates to tox
tox is a mature test environment manager.
uv-matrix is intentionally smaller. It delegates interpreter discovery, environment creation, and dependency resolution to uv, then focuses on one job: expanding matrix definitions into commands.
Instead of encoding combinations into environment names, uv-matrix keeps matrix axes explicit in pyproject.toml.
Where to next
Installation — install uv-matrix into a uv project.
Quickstart — set up pytest and ruff matrices and run them.
Usage — the
runandlistcommands and their flags.Configuration — the full
[tool.uv-matrix]reference.