# Coverage.py

Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, noting which parts of the code have been executed, then analyzes the source to identify code that could have been executed but was not.

Coverage measurement is typically used to gauge the effectiveness of tests. It can show which parts of your code are being exercised by tests, and which are not.

The latest version is coverage.py 7.13.5, released March 17, 2026. It is supported on:

- Python 3.10 through 3.15 alpha, including free-threading.

- PyPy3 versions 3.10 and 3.11.

## For Enterprise

Available as part of the Tidelift Subscription.
Coverage and thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use. If you want the flexibility of open source and the confidence of commercial-grade software, this is for you. Learn more.

## Quick start

Getting started is easy:

1. Install coverage.py:

       $ python3 -m pip install coverage

   For more details, see Installation.

2. Use `coverage run` to run your test suite and gather data. However you normally run your test suite, you can use your test runner under coverage.

   Tip

   If your test runner command starts with “python”, replace the initial “python” with “coverage run”.

   `python something.py` becomes `coverage run something.py`

   `python -m amodule` becomes `coverage run -m amodule`

   Other instructions for specific test runners:

   - pytest
   - unittest
   - nosetest

   If you usually use:

       $ pytest arg1 arg2 arg3

   then you can run your tests under coverage with:

       $ coverage run -m pytest arg1 arg2 arg3

   Many people choose to use the pytest-cov plugin, but for most purposes, it is unnecessary.

   Change your python command name to “coverage run”, so this:

       $ python3 -m unittest discover

   becomes:

       $ coverage run -m unittest discover

   Note

   Nose has been unmaintained since at least 2015. You should seriously consider using a different test runner.

   Change this:

       $ nosetests arg1 arg2

   to:

       $ coverage run -m nose arg1 arg2

   Coverage doesn’t distinguish between tests and the code being tested. We recommend that you include your tests in coverage measurement.

   To limit coverage measurement to code in the current directory, and also find files that weren’t executed at all, add the `--source=.` argument to your coverage command line. You can also specify source files to measure or exclude code from measurement.

3. Use `coverage report` to report on the results:

       $ coverage report -m
       Name                      Stmts   Miss  Cover   Missing
       -------------------------------------------------------
       my_program.py                20      4    80%   33-35, 39
       my_other_module.py           56      6    89%   17-23
       -------------------------------------------------------
       TOTAL                        76     10    87%

4. For a nicer presentation, use `coverage html` to get annotated HTML listings detailing missed lines:

       $ coverage html
       Wrote HTML report to htmlcov/index.html

   Then open htmlcov/index.html in your browser to see a report like this.

## Capabilities

Coverage.py can do a number of things:

- By default it will measure line (statement) coverage.

- It can also measure branch coverage.

- It can tell you what tests ran which lines.

- It can produce reports in a number of formats: text, HTML, XML, LCOV, and JSON.

- For advanced uses, there’s an API, and the result data is available in a SQLite database.

## Using coverage.py

There are a few different ways to use coverage.py. The simplest is the command line, which lets you run your program and see the results. If you need more control over how your project is measured, you can use the API.

Some test runners provide coverage integration to make it easy to use coverage.py while running tests. For example, pytest has the pytest-cov plugin.

You can fine-tune coverage.py’s view of your code by directing it to ignore parts that you know aren’t interesting. See Specifying source files and Excluding code from coverage.py for details.

## Getting help

If the FAQ doesn’t answer your question, you can discuss coverage.py or get help using it on the Python discussion forums or in the Python Discord. If you ping me (`@nedbat`), there’s a higher chance I’ll see the post.

Bug reports are gladly accepted at the GitHub issue tracker. GitHub also hosts the code repository.

Professional support for coverage.py is available as part of the Tidelift Subscription.

I can be reached in a number of ways. I’m happy to answer questions about using coverage.py.

For news and other chatter, follow the project on Mastodon: @coveragepy@hachyderm.io.

## More information

- Installation
- For enterprise
- Commands
- Configuration reference
- Messages
- Specifying source files
- Excluding code from coverage.py
- Branch coverage measurement
- Managing processes
- Measurement contexts
- Coverage.py API
- How coverage.py works
- Plug-ins
- Other resources
- Contributing to coverage.py
- Things that cause trouble
- FAQ and other help
- Change history
- Migrating between versions
- Sleepy Snake