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 before pytest starts. It installs selected dependencies and installs the project itself when it is configured as a package. Flat, nonpackaged projects run from source instead.

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