pytest

pytest 8+

Quick reference for the pytest CLI: test discovery, selection, fixtures, markers, parallelism, parametrize, and coverage integration — with common options and practical examples.

34 commands

Help

pytest --version

Print pytest version and the import library paths it found.

pytest --version

pytest --help

Show every pytest CLI flag with one-line descriptions.

-h

pytest --help | less

Discovery

pytest

Run every test in the current directory and subdirectories following the default discovery rules (`test_*.py` / `*_test.py`, functions named `test_*`, classes named `Test*`).

-x; --maxfail=1; --co; --collect-only; -q; -v; -k <expr>; -m <marker>; --no-header

pytest

pytest <path>

Run only tests under the specified file or directory. Globs are supported.

<path>; tests/; tests/test_x.py; tests/test_x.py::test_y

pytest tests/unit

pytest tests/test_user.py::TestUser::test_create

Run a single test by its full node path: module / class / function.

pytest tests/test_user.py::test_create_user

Selection

pytest -k <expr>

Run tests whose names match the substring / Python expression (`-k 'user and not slow'`).

-k 'pattern'; -k 'ClassName and method'

pytest -k 'create or update'

pytest -m <marker>

Run only tests with a given marker (markers must be registered in `pyproject.toml` or pytest.ini to suppress warnings).

-m slow; -m 'not slow'

pytest -m 'not integration'

pytest --co

Collect-only mode — list the tests pytest would run without executing them. Great for CI previews.

--collect-only; -q

pytest --co -q

Stop / report

pytest -x

Stop on the first failure. Use `--maxfail=N` for a custom threshold.

--maxfail=1; --maxfail=3; --exitfirst; -x

pytest -x --maxfail=2

pytest --tb=short

Choose traceback style: `long` (default), `short`, `line`, `native`, `no` (suppress).

long; short; line; native; no

pytest --tb=short

pytest -v

Verbose mode — show each test function's full node id. Combine with `-vv` for even more detail.

-v; -vv; --no-header; --no-summary; -q; -rA

pytest -v --no-header

pytest -s

Disable stdout/stderr capture — let print() statements stream to your terminal (rare; use `capfd` fixture inside tests instead).

--capture=no; -s; --capture=fd

pytest -s tests/test_print.py

pytest --durations=10

Show the 10 slowest tests in the final report (use `--durations=0` for all).

--durations=10; --durations=min=0.5

pytest --durations=10

pytest -rA

Print a summary of extra test outcomes: `E` errors, `F` failures, `s` skips, `x` xfails, `A` all.

-rA; -rfE; -rs; -rxX

pytest -rA

Re-run

pytest --lf

Last-failed — re-run only the tests that failed in the previous run. Pair with `--ff` to order failing tests first.

--lf; --last-failed; --ff; --failed-first; --cache-clear

pytest --lf

pytest --sw

Stepwise mode — stop at the first failure and resume from there on next invocation.

--stepwise; --stepwise-skip; --stepwise-skip-some

pytest --sw

Parametrize / fixtures

pytest --fixtures

List every fixture visible in the current test scope (project-wide when run from the repo root).

--fixtures; --fixtures-per-test

pytest --fixtures -q

pytest --markers

List every marker defined (registered in pytest.ini / pyproject.toml).

--markers

pytest --markers

Parallelism

pytest -n <N>

Run tests in parallel across `<N>` worker processes (pytest-xdist plugin). Use `auto` for CPU-count workers.

-n auto; -n 4; --dist loadscope; --dist loadfile; -p no:cacheprovider

pytest -n auto

pytest --dist loadgroup

Group tests by `@pytest.mark.group_*` markers (xdist) so a single group runs in a single worker — useful for resource-conflicting tests.

--dist loadgroup; --dist loadscope

pytest -n 4 --dist loadgroup

Output

pytest --junitxml=<file>

Emit a JUnit-style XML report (consumed by GitHub Actions, GitLab, Jenkins, CircleCI).

--junitxml=report.xml; --junit-xml=report.xml

pytest --junitxml=pytest-report.xml

pytest --html=<file>

Generate a self-contained HTML test report (pytest-html plugin).

--html=report.html; --self-contained-html

pytest --html=report.html --self-contained-html

pytest --cov=<pkg>

Run tests under coverage measurement (pytest-cov plugin). Combine with `--cov-report=` to choose the output format.

--cov=src; --cov-report=term; --cov-report=xml; --cov-report=html; --cov-fail-under=80

pytest --cov=src --cov-report=term-missing --cov-fail-under=80

Watch / auto-rerun

pytest --looponfail

Re-run failing tests on every save until they pass (deprecated in pytest 7+, use pytest-watch / pytest-xdist --loop-onfail).

--looponfail

pytest --looponfail

ptw

Run pytest in watch mode — re-runs the suite on every file change (pytest-watch, installed via pip).

--clear; --runner 'pytest -x'; --now

ptw -- -x

Config

pytest -c <file>

Override the pytest config file (default `pytest.ini` / `pyproject.toml [tool.pytest.ini_options]` / `tox.ini` / `setup.cfg`).

-c pytest.ini; -c tests/pytest-cfg.ini

pytest -c tests/pytest-cfg.ini

pytest -p <plugin>

Load a plugin on the CLI (e.g. `pytest -p no:cacheprovider` disables caching).

-p django; -p asyncio; -p no:warnings; -p no:cacheprovider

pytest -p no:cacheprovider

Debug

pytest --trace

Drop into `pdb.set_trace()` at the start of the first test (use `--trace-cli` for non-CLI crashes).

--trace; --trace-cli

pytest --trace tests/test_user.py::test_login

pytest --pdb

Auto-launch pdb on every test failure or error.

--pdb; --pdbcls=IPython.terminal.debugger.TerminalPdb

pytest --pdb -x

pytest --setup-show

Show the setup / teardown trace of fixtures while running (use `--setup-plan` for trace without execution).

--setup-show; --setup-plan

pytest --setup-show tests/test_db.py

Warnings

pytest -W <filter>

Forward Python warnings as if pytest raised them. Filters follow the `-W` action module spec.

-W error; -W ignore::DeprecationWarning; -W default

pytest -W error::DeprecationWarning

pytest --strict-markers

Treat unregistered markers as errors — catches typos in `@pytest.mark.slow` etc.

--strict-markers; --strict-config; --strict

pytest --strict-markers

Async

pytest -p asyncio

-p asyncio; --asyncio-mode=auto

pytest --asyncio-mode=auto

Misc

pytest --rootdir=<dir>

Override the project root pytest uses for config discovery.

--rootdir=.; --import-mode=importlib

pytest --rootdir=. tests/

Related command cheatsheets

Python Development

uv

Quick reference for the uv CLI: Python project init, dependency management, virtual environments, lockfile resolution, tool runners, and self-update — with common options and practical examples.

39 commands

uv 0.4+

Python Development

conda

Quick reference for Conda CLI commands: environment management, package install / search, channels, lockfiles, configuration, and cleanup — with common options and practical examples.

40 commands

Conda 24+

Python Development

pip

Quick reference for the pip package installer CLI: install / uninstall / inspect packages, virtual environments, requirements files, configuration, and index management — with common options and practical examples.

37 commands

pip 24+

Trademark & Use Notice

These command-line tool cheatsheets are open community references. The names, logos, and trademarks of the tools referenced here (such as Git™, Docker™, Kubernetes®, kubectl, PostgreSQL®, MySQL®, Redis™, MongoDB®, Linux™, PowerShell™, Vim™, and others) are the property of their respective owners and are used here solely for identification and reference purposes.

All content in these cheatsheets is independently authored as a simplified, self-contained reference. It is not affiliated with, endorsed by, or sourced from any official documentation. Command listings, flag descriptions, and examples are original simplifications; for authoritative information please consult the official documentation of each tool.

Command syntax and option flags may differ across tool versions. The version tags shown reflect stable releases; behavior may differ in other versions. This cheatsheet does not imply any preference or recommendation by the trademark holders.

If a trademark or copyright owner believes that any content on this site infringes their rights, please send an email to [email protected]. Upon receiving valid proof of rights, we will modify or remove the relevant content within a reasonable period.

This website assumes no legal liability for any direct or indirect losses arising from the use of information presented on these pages.

About pytest

pytest is the de-facto standard Python testing framework. It was created by Holger Krekel and released in 2008 (originally as a successor to the older `py` library). pytest simplifies the boilerplate of Python's stdlib `unittest` — tests are plain `def test_*():` functions, no class boilerplate required — and ships with a powerful fixture system, parametrize, markers, and a rich plugin ecosystem (pytest-cov, pytest-xdist, pytest-mock, pytest-django, pytest-asyncio, hypothesis, etc.). The current stable line is pytest 8+ (8.3+). pytest auto-discovers tests via the default naming convention (`test_*.py` / `*_test.py`), runs them in a deterministic order, and produces rich diffs on assertion failures. pytest can run unittest / nose-style tests too. Common companion CLI is `coverage` (run `coverage run -m pytest` then `coverage report`). pytest never uploads your code; all test execution is local.

Cheatsheet version 1.0.0