How do I run pytest in a uv project?

Run `uv run pytest` from the project root. uv syncs the virtual environment against `pyproject.toml` and `uv.lock` before invoking pytest, so tests run against the locked dependency versions. If pytest is not declared as a dependency, `uv run --with pytest pytest` injects it for one invocation without touching the lockfile.

How do I run a single pytest test or filter by name with uv?

Target a file with `uv run pytest tests/test_api.py`, a single test with `uv run pytest tests/test_api.py::test_login`, or a keyword pattern with `uv run pytest -k "login or signup"`. To run only tests tagged with a marker like `slow`, use `uv run pytest -m slow`.

How do I make pytest stop after the first failure with uv?

Pass `-x` to halt after the first failing test: `uv run pytest -x`. To stop after a specific number of failures, use `--maxfail=N`, for example `uv run pytest --maxfail=3`. Combine with `--tb=short` to keep tracebacks concise while iterating on a failing change.

How do I re-run only failed pytest tests with uv?

Run `uv run pytest --last-failed` to skip everything that passed on the previous run; pytest reads the cached results from `.pytest_cache/`. Use `--fail-first` to run previously failed tests first and then continue through the rest of the suite, useful for a focused fix cycle followed by full re-verification.

How to Run Tests Using uv

by Tim Hopper

uv Testing

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.

If pytest is not in the project’s dependencies and you don’t want to add it, inject it at runtime:

uv run --with pytest pytest

Run a Subset of Tests

Target a single file, a single function, or a keyword pattern:

uv run pytest tests/test_api.py
uv run pytest tests/test_api.py::test_login
uv run pytest -k "login or signup"

The -k flag matches against test names, so -k "login or signup" runs every test whose name contains either word.

Run only tests tagged with a marker:

uv run pytest -m slow

Control Output

Show each test name instead of a dot:

uv run pytest -v

Print print() output and logging to the terminal (pytest captures them by default):

uv run pytest -s

Shorten tracebacks to just the failing assertion:

uv run pytest --tb=short

Stop Early on Failure

Stop after the first failure:

uv run pytest -x

Stop after n failures:

uv run pytest --maxfail=3

Re-run Only Failed Tests

pytest records which tests passed and failed in .pytest_cache/. On the next run, --last-failed skips everything that passed:

uv run pytest --last-failed

Combine with --fail-first to run the previously failed tests first, then the rest:

uv run pytest --fail-first

Set Persistent Defaults

Add flags to pyproject.toml so they apply on every run without typing them:

[tool.pytest.ini_options]
addopts = "-x --tb=short"

Any flags passed on the command line are appended to addopts, so uv run pytest -v becomes -x --tb=short -v.

Learn More

Setting up testing with pytest and uv walks through creating a project with tests from scratch
How to test against multiple Python versions using uv covers --python for cross-version testing
How to run tests in parallel with pytest-xdist distributes tests across CPU cores
How to fix common pytest errors with uv covers ModuleNotFoundError and other setup issues
pytest reference

Last updated on May 13, 2026

How to run tests in parallel with pytest-xdist How to run the IPython shell in your uv project

Please submit corrections and feedback...