---
name: "python3.9-coverage"
section: "1"
platform: "linux"
package: "python3-coverage"
version: "5.1+dfsg.1-2+b2"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/python3.9-coverage"
---

# python3.9-coverage(1)

measure code coverage of Python program execution

## NAME

python-coverage - measure code coverage of Python program execution

## SYNOPSIS

```
python-coverage command [ option ... ]
python-coverage help [ command ]
```

## DESCRIPTION

**python-coverage** executes a Python program, measures which of its statements are executed and which are not, and reports these coverage measurements.

## COMMAND OVERVIEW

- **python-coverage annotate**

  Annotate source files with execution information.

- **python-coverage combine**

  Combine a number of data files.

- **python-coverage debug**

  Display diagnostic information about the internals of this program.

- **python-coverage erase**

  Erase previously collected coverage data.

- **python-coverage help**

  Get help on using coverage.py.

- **python-coverage html**

  Create an HTML report.

- **python-coverage report**

  Report coverage stats on modules.

- **python-coverage run**

  Run a Python program and measure code execution.

- **python-coverage xml**

  Create an XML report of coverage results.

## GLOBAL OPTIONS

- **--help, -h**

  Describe how to use Coverage, in general or a command.

- **--rcfile *RCFILE***

  Specify configuration file *RCFILE*. Defaults to **.coveragerc**.

- **--omit *PATTERN* ...**

  Omit files when their filename matches one of these PATTERNs. Usually needs quoting on the command line.

- **--include *PATTERN* ...**

  Include files only when their filename path matches one of these PATTERNs. Usually needs quoting on the command line.

## COMMAND REFERENCE

**annotate**

Options:

- **-d *DIR*, --directory *DIR***

  Write the output files to DIR.

- **-i, --ignore-errors**

  Ignore errors while reading source files.

**combine** *PATH* *PATH* \[ ... \]

Combine data from multiple coverage files *PATH*, collected with **run -p**. The combined results are written to a single file representing the union of the data.

**debug** *topic*

Display information on the internals of coverage.py, for diagnosing problems.

Topics are:

- •

  *data*, to show a summary of the collected data.

- •

  *sys*, to show installation information.

**erase**

Erase previously collected coverage data.

**help** \[ *command* \]

Describe how to use Coverage.

**html** \[ *option* ... \] \[ *MODULE* ... \]

Create an HTML report of the coverage of each *MODULE* file. Each file gets its own page, with the source decorated to show executed, excluded, and missed lines.

Options:

- **-d *DIR*, --directory *DIR***

  Write the output files to *DIR*.

- **--title *TITLE***

  Use the text string *TITLE* as the title on the HTML.

- **--fail-under *MIN***

  Exit with a status of 2 if the total coverage is less than *MIN*.

- **-i, --ignore-errors**

  Ignore errors while reading source files.

**report** \[ *option* ... \] \[ *MODULE* ... \]

Report coverage statistics on each *MODULE*.

Options:

- **--fail-under *MIN***

  Exit with a status of 2 if the total coverage is less than *MIN*.

- **-i, --ignore-errors**

  Ignore errors while reading source files.

- **-m, --show-missing**

  Show line numbers of statements in each module that weren't executed.

**run** \[ *options* ... \] *PROGRAMFILE* \[ *program\_options* \]

Run a Python program *PROGRAMFILE*, measuring code execution.

Options:

- **-a, --append**

  Append coverage data to .coverage, otherwise it is started clean with each run.

- **--branch**

  Measure branch coverage in addition to statement coverage.

- **--debug *DEBUGOPT*,...**

  Debug options *DEBUGOPT*, separated by commas

- **-L, --pylib**

  Measure coverage even inside the Python installed library, which isn't done by default.

- **-p, --parallel-mode**

  Append the machine name, process id and random number to the **.coverage** data file name to simplify collecting data from many processes.

- **--timid**

  Use a simpler but slower trace method. Try this if you get seemingly impossible results!

- **--source *SOURCE* ...**

  A list of packages or directories of code to be measured.

**xml** \[ *options* ... \] \[ *MODULES* ... \]

Generate an XML report of coverage results on each *MODULE*.

Options:

- **--fail-under *MIN***

  Exit with a status of 2 if the total coverage is less than *MIN*.

- **-i, --ignore-errors**

  Ignore errors while reading source files.

- **-o *OUTFILE***

  Write the XML report to *OUTFILE*. Defaults to **coverage.xml**.

## ENVIRONMENT VARIABLES

COVERAGE\_FILE

Path to the file where coverage measurements are collected to and reported from. Default: **.coverage** in the current working directory.

COVERAGE\_OPTIONS

Space-separated series of command-line options to **python-coverage**. Default: empty.

## HISTORY

The **python-coverage** command is a Python program which calls the **coverage** Python library to do all the work.

The library was originally developed by Gareth Rees, and is now developed by Ned Batchelder.

This manual page was written to document the **python-coverage** command for Debian. This is free software: you may copy, modify and/or distribute this work under the terms of the *GNU General Public License, version 3 or later* as published by the Free Software Foundation, version 3 or later. No warranty expressed or implied.

On Debian systems, the complete text of the GNU General Public License version 3 can be found in the file */usr/share/common-licenses/GPL-3*.

## AUTHOR

Ben Finney \<ben+python@benfinney.id.au\>

## COPYRIGHT

Copyright © 2010–2017 Ben Finney \<bignose@debian.org\>