coverage.py Cheat Sheet

1Install & run7.15

pip install coverage★
Installs the coverage CLI. pip install coverage[toml] on older Pythons for pyproject.toml config (built-in on 3.11+).
coverage run -m pytest★
The core idea: replace python with coverage run. It launches and traces the process. Works with any runner: coverage run -m unittest, coverage run prog.py args.
coverage run --source=mypkg -m pytest★
Limit what's measured to your package — otherwise stdlib and dependencies inflate/pollute the numbers. Set once in config instead (card 4).
coverage run --append ... · coverage erase
--append adds to existing data (multiple runs); erase wipes the .coverage file to start clean.

2Reportsterminal, HTML, XML

coverage report -m★
Terminal table of statements / missed / percent. -m adds the missing line numbers — the fastest way to see what's untested.
coverage html # -> htmlcov/index.html★
Annotated source you can click through — green = run, red = missed. The best view for exploring gaps.
coverage xml # Cobertura, for CI / Codecov coverage json · coverage lcov★
Machine-readable outputs for CI dashboards (Codecov/Coveralls take xml/lcov).
coverage report --skip-covered --sort=cover
Hide fully-covered files and sort by percentage — focus on the weakest spots.

3Branch coveragebeyond lines

coverage run --branch -m pytest★
Measures both directions of every branch, not just whether a line ran. Catches an if whose else path is never taken — line coverage misses this.
# report gains Branch / BrPart columns; -m shows e.g. 34->exit★
Partial branches show as 34->36 / 34->exit in the missing column — the line ran but one outgoing path never did.
# enable permanently in config: branch = true
Set it in [tool.coverage.run] so every run measures branches (card 4). Branch coverage is the recommended default.

4Config (pyproject)one source of truth

# pyproject.toml [tool.coverage.run] source = ["mypkg"] branch = true★
Auto-discovered config — no CLI flags needed after this. Also .coveragerc, setup.cfg, or tox.ini ([coverage:run] there).
[tool.coverage.report] show_missing = true skip_covered = true precision = 2★
Report defaults so plain coverage report does the right thing. precision sets decimal places on percentages.
[tool.coverage.html] directory = "htmlcov"
Per-format sections: [tool.coverage.html], [tool.coverage.xml], [tool.coverage.paths] (to merge equivalent paths across environments).

5Exclude & omitwhat shouldn't count

def debug_dump(self): # pragma: no cover ...★
Inline exclusion — # pragma: no cover drops a line/block from measurement (e.g. defensive code you won't test).
[tool.coverage.report] exclude_also = [ "if TYPE_CHECKING:", "raise NotImplementedError", "if __name__ == .__main__.:", ]★
Regex patterns to exclude everywhere. exclude_also adds to the built-in defaults (use exclude_lines to replace them).
[tool.coverage.run] omit = ["*/tests/*", "*/migrations/*", "*/__main__.py"]
omit = whole files (path globs); exclude_* = lines within files. Don't confuse them. include restricts to a set.

6fail_under & CIenforce a threshold

[tool.coverage.report] fail_under = 90★
Gate on coverage: coverage report exits non-zero (2) if total is below 90% — fail the CI job. Or one-off: coverage report --fail-under=90.
# typical CI sequence coverage run -m pytest && coverage report && coverage xml★
Run, print the table (which enforces fail_under), and emit coverage.xml to upload to a coverage service.
coverage report --format=markdown # for PR comments / summaries
Markdown/total formats are handy for CI job summaries and bots.

7pytest-covthe pytest front-end

pip install pytest-cov pytest --cov=mypkg --cov-report=term-missing --cov-report=html★
One command to run tests + coverage in pytest. It wraps the same engine, so your [tool.coverage.*] config still applies.
pytest --cov=mypkg --cov-branch --cov-fail-under=90 --cov-report=xml★
Branch coverage, the CI gate, and XML output as pytest flags. Mirrors the plain-coverage options.
# plain `coverage run -m pytest` is enough for most projects; # pytest-cov shines with pytest-xdist parallel test runs.
The docs note pytest-cov is often unnecessary — but it handles -n auto (xdist) subprocess collection cleanly.

8Parallel & contextscombine + who-tested-what

# [tool.coverage.run] parallel = true coverage run -m pytest # writes .coverage.HOST.PID files coverage combine # merge into one .coverage coverage report★
Parallel mode writes one data file per process; combine merges them. Always combine before reporting or you'll see only one worker's data.
[tool.coverage.run] concurrency = ["thread", "multiprocessing"]
Tell coverage how your code runs concurrently (also greenlet, gevent, eventlet) so it traces threads/subprocesses correctly.
[tool.coverage.run] dynamic_context = "test_function" # then: coverage html --show-contexts
Contexts record which test covered each line — the HTML report can show it. Great for finding redundant or missing tests.

!Common gotchasread before shipping

always set source= / --source
Without it, coverage reports on every imported module (stdlib, site-packages) — misleading totals and huge reports. Scope to your package.
coverage run -m pytest, not just pytest
Coverage must launch the process to trace it. Running pytest then coverage report measures nothing — use coverage run or the pytest-cov plugin.
combine before report (parallel/xdist)
Parallel runs leave several .coverage.* files. Forget coverage combine and your percentage reflects one worker only.
100% coverage ≠ well tested
Coverage shows what ran, not what was asserted. Use branch coverage and real assertions; a high number can still hide bugs.
omit vs exclude
omit/include filter whole files (path globs); exclude_lines/exclude_also filter lines by regex. Using the wrong one silently does nothing.
fail_under rounds at `precision`
The threshold check uses the reported (rounded) total. At precision = 0, 89.5% displays as 90% and can pass — set precision deliberately.
don't commit .coverage
It's a local SQLite data file (plus htmlcov/). Add both to .gitignore.

coverage.py cheat sheet