Skip to content

How to Run Tests Using uv

If your project lists pytest as a dev dependency, uv runs 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

Show print() output as tests run by disabling stdout/stderr capture:

uv run pytest -s

To show log messages as tests run, enable live logging separately with uv run pytest --log-cli-level=INFO.

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 failures in .pytest_cache/. Use --last-failed to rerun those tests:

uv run pytest --last-failed

If there are no cached failures, --last-failed runs all selected tests. After fixing failures, run the full suite to check for regressions.

Use --failed-first instead to run the previously failed tests first, then the rest:

uv run pytest --failed-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.

Last updated on