Command line usage — Coverage.py 7.8.0 documentation (original) (raw)

When you install coverage.py, a command-line script called coverage is placed on your path. To help with multi-version installs, it will also create a coverage3 alias, and a coverage-X.Y alias, depending on the version of Python you’re using. For example, when installing on Python 3.10, you will be able to use coverage, coverage3, or coverage-3.10 on the command line.

Coverage.py has a number of commands:

Help is available with the help command, or with the --help switch on any other command:

$ coverage help $ coverage help run $ coverage run --help

Version information for coverage.py can be displayed withcoverage --version:

$ coverage --version Coverage.py, version 7.8.0 with C extension Documentation at https://coverage.readthedocs.io/en/7.8.0

Any command can use a configuration file by specifying it with the--rcfile=FILE command-line switch. Any option you can set on the command line can also be set in the configuration file. This can be a better way to control coverage.py since the configuration file can be checked into source control, and can provide options that other invocation techniques (like test runner plugins) may not offer. See Configuration reference for more details.

Execution: coverage run

You collect execution data by running your Python program with the runcommand:

$ coverage run my_program.py arg1 arg2 blah blah ..your program's output.. blah blah

Your program runs just as if it had been invoked with the Python command line. Arguments after your file name are passed to your program as usual insys.argv. Rather than providing a file name, you can use the -m switch and specify an importable module name instead, just as you can with the Python -m switch:

$ coverage run -m packagename.modulename arg1 arg2 blah blah ..your program's output.. blah blah

Note

In most cases, the program to use here is a test runner, not your program you are trying to measure. The test runner will run your tests and coverage will measure the coverage of your code along the way.

There are many options:

$ coverage run --help Usage: coverage run [options] [program options]

Run a Python program, measuring code execution.

Options: -a, --append Append coverage data to .coverage, otherwise it starts clean each time. --branch Measure branch coverage in addition to statement coverage. --concurrency=LIBS Properly measure code using a concurrency library. Valid values are: eventlet, gevent, greenlet, multiprocessing, thread, or a comma-list of them. --context=LABEL The context label to record for this coverage run. --data-file=OUTFILE Write the recorded coverage data to this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -m, --module is an importable Python module, not a script path, to be run as 'python -m' would run it. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -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 data file name to simplify collecting data from many processes. --source=SRC1,SRC2,... A list of directories or importable names of code to measure. --timid Use the slower Python trace function core. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

If you want branch coverage measurement, use the --branchflag. Otherwise only statement coverage is measured.

You can specify the code to measure with the --source, --include, and--omit switches. See Specifying source files for details of their interpretation. Remember to put options for run after “run”, but before the program invocation:

$ coverage run --source=dir1,dir2 my_program.py arg1 arg2 $ coverage run --source=dir1,dir2 -m packagename.modulename arg1 arg2

Note

Specifying --source on the coverage run command line won’t affect subsequent reporting commands like coverage xml. Use the source setting in the configuration file to apply the setting uniformly to all commands.

Coverage.py can measure multi-threaded programs by default. If you are using more other concurrency support, with the multiprocessing, greenlet,eventlet, or gevent libraries, then coverage.py can get confused. Use the--concurrency switch to properly measure programs using these libraries. Give it a value of multiprocessing, thread, greenlet, eventlet, or gevent. Values other than thread require the C extension.

You can combine multiple values for --concurrency, separated with commas. You can specify thread and also one of eventlet, gevent, orgreenlet.

If you are using --concurrency=multiprocessing, you must set your other options in the configuration file. Options on the command line will not be passed to the processes that multiprocessing creates. Best practice is to use the configuration file for all options.

If you are measuring coverage in a multi-process program, or across a number of machines, you’ll want the --parallel-mode switch to keep the data separate during measurement. See Combining data files: coverage combine below.

You can specify a static context for a coverage run with--context. This can be any label you want, and will be recorded with the data. See Measurement contexts for more information.

By default, coverage.py does not measure code installed with the Python interpreter, for example, the standard library. If you want to measure that code as well as your own, add the -L (or --pylib) flag.

If your coverage results seem to be overlooking code that you know has been executed, try running coverage.py again with the --timid flag. This uses a simpler but slower trace method, and might be needed in rare cases.

In Python 3.12 and above, you can try an experimental core based on the newsys.monitoring module by defining aCOVERAGE_CORE=sysmon environment variable. This should be faster, though plugins and dynamic contexts are not yet supported with it.

Coverage.py sets an environment variable, COVERAGE_RUN to indicate that your code is running under coverage measurement. The value is not relevant, and may change in the future.

These options can also be set in the [run] section of your .coveragerc file.

Warnings

During execution, coverage.py may warn you about conditions it detects that could affect the measurement process. The possible warnings include:

Couldn’t parse Python file XXX (couldnt-parse)

During reporting, a file was thought to be Python, but it couldn’t be parsed as Python.

Trace function changed, data is likely wrong: XXX (trace-changed)

Coverage measurement depends on a Python setting called the trace function. Other Python code in your product might change that function, which will disrupt coverage.py’s measurement. This warning indicates that has happened. The XXX in the message is the new trace function value, which might provide a clue to the cause.

Module XXX has no Python source (module-not-python)

You asked coverage.py to measure module XXX, but once it was imported, it turned out not to have a corresponding .py file. Without a .py file, coverage.py can’t report on missing lines.

Module XXX was never imported (module-not-imported)

You asked coverage.py to measure module XXX, but it was never imported by your program.

No data was collected (no-data-collected)

Coverage.py ran your program, but didn’t measure any lines as executed. This could be because you asked to measure only modules that never ran, or for other reasons.

To debug this problem, try using run --debug=trace to see the tracing decision made for each file.

Module XXX was previously imported, but not measured (module-not-measured)

You asked coverage.py to measure module XXX, but it had already been imported when coverage started. This meant coverage.py couldn’t monitor its execution.

Already imported a file that will be measured: XXX (already-imported)

File XXX had already been imported when coverage.py started measurement. Your setting for --source or --include indicates that you wanted to measure that file. Lines will be missing from the coverage report since the execution during import hadn’t been measured.

--include is ignored because --source is set (include-ignored)

Both --include and --source were specified while running code. Both are meant to focus measurement on a particular part of your source code, so--include is ignored in favor of --source.

Conflicting dynamic contexts (dynamic-conflict)

The [run] dynamic_context option is set in the configuration file, but something (probably a test runner plugin) is also calling theCoverage.switch_context() function to change the context. Only one of these mechanisms should be in use at a time.

sys.monitoring isn’t available in this version, using default core (no-sysmon)

You requested to use the sys.monitoring measurement core, but are running on Python 3.11 or lower where it isn’t available. A default core will be used instead.

sys.monitoring can’t measure branches in this version, using default core (no-sysmon)

You requested the sys.monitoring measurement core and also branch coverage. This isn’t supported until the later alphas of Python 3.14. A default core will be used instead.

sys.monitoring doesn’t yet support dynamic contexts, using default core (no-sysmon)

You requested the sys.monitoring measurement core and also dynamic contexts. This isn’t supported by coverage.py yet. A default core will be used instead.

Individual warnings can be disabled with the disable_warnings configuration setting. It is a list of the short parenthetical nicknames in the warning messages. For example, to silence “No data was collected (no-data-collected)”, add this to your configuration file:

[run] disable_warnings = no-data-collected

[tool.coverage.run] disable_warnings = ["no-data-collected"]

[coverage:run] disable_warnings = no-data-collected

Data file

Coverage.py collects execution data in a file called “.coverage”. If need be, you can set a new file name with the COVERAGE_FILE environment variable. This can include a path to another directory.

By default, each run of your program starts with an empty data set. If you need to run your program multiple times to get complete data (for example, because you need to supply different options), you can accumulate data across runs with the --append flag on the run command.

Combining data files: coverage combine

Often test suites are run under different conditions, for example, with different versions of Python, or dependencies, or on different operating systems. In these cases, you can collect coverage data for each test run, and then combine all the separate data files into one combined file for reporting.

The combine command reads a number of separate data files, matches the data by source file name, and writes a combined data file with all of the data.

Coverage normally writes data to a filed named “.coverage”. The run --parallel-mode switch (or [run] parallel=True configuration option) tells coverage to expand the file name to include machine name, process id, and a random number so that every data file is distinct:

.coverage.Neds-MacBook-Pro.local.88335.316857 .coverage.Geometer.8044.799674

You can also define a new data file name with the [run] data_file option.

Once you have created a number of these files, you can copy them all to a single directory, and use the combine command to combine them into one .coverage data file:

You can also name directories or files to be combined on the command line:

$ coverage combine data1.dat windows_data_files/

Coverage.py will collect the data from those places and combine them. The current directory isn’t searched if you use command-line arguments. If you also want data from the current directory, name it explicitly on the command line.

When coverage.py combines data files, it looks for files named the same as the data file (defaulting to “.coverage”), with a dotted suffix. Here are some examples of data files that can be combined:

.coverage.machine1 .coverage.20120807T212300 .coverage.last_good_run.ok

An existing combined data file is ignored and re-written. If you want to usecombine to accumulate results into the .coverage data file over a number of runs, use the --append switch on the combine command. This behavior was the default before version 4.2.

If any of the data files can’t be read, coverage.py will print a warning indicating the file and the problem.

The original input data files are deleted once they’ve been combined. If you want to keep those files, use the --keep command-line option.

$ coverage combine --help Usage: coverage combine [options] ...

Combine data from multiple coverage files. The combined results are written to a single file representing the union of the data. The positional arguments are data files or directories containing data files. If no paths are provided, data files in the default data file's directory are combined.

Options: -a, --append Append coverage data to .coverage, otherwise it starts clean each time. --data-file=DATAFILE Base name of the data files to operate on. Defaults to '.coverage'. [env: COVERAGE_FILE] --keep Keep original coverage files, otherwise they are deleted. -q, --quiet Don't print messages about what is happening. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

Re-mapping paths

To combine data for a source file, coverage has to find its data in each of the data files. Different test runs may run the same source file from different locations. For example, different operating systems will use different paths for the same file, or perhaps each Python version is run from a different subdirectory. Coverage needs to know that different file paths are actually the same source file for reporting purposes.

You can tell coverage.py how different source locations relate with a[paths] section in your configuration file (see [paths]). It might be more convenient to use the [run] relative_filessetting to store relative file paths (see relative_files).

If data isn’t combining properly, you can see details about the inner workings with --debug=pathmap.

Erase data: coverage erase

To erase the collected data, use the erase command:

$ coverage erase --help Usage: coverage erase [options]

Erase previously collected coverage data.

Options: --data-file=DATAFILE Base name of the data files to operate on. Defaults to '.coverage'. [env: COVERAGE_FILE] --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

If your configuration file indicates parallel data collection, erase will remove all of the data files.

Reporting

Coverage.py provides a few styles of reporting, with the report, html,annotate, json, lcov, and xml commands. They share a number of common options.

The command-line arguments are module or file names to report on, if you’d like to report on a subset of the data collected.

The --include and --omit flags specify lists of file name patterns. They control which files to report on, and are described in more detail inSpecifying source files.

The -i or --ignore-errors switch tells coverage.py to ignore problems encountered trying to find source files to report on. This can be useful if some files are missing, or if your Python execution is tricky enough that file names are synthesized without real source files.

If you provide a --fail-under value, the total percentage covered will be compared to that value. If it is less, the command will exit with a status code of 2, indicating that the total coverage was less than your target. This can be used as part of a pass/fail condition, for example in a continuous integration server. This option isn’t available for annotate.

These options can also be set in your .coveragerc file. SeeConfiguration: [report].

Coverage summary: coverage report

The simplest reporting is a textual summary produced with report:

$ coverage report Name Stmts Miss Cover

my_program.py 20 4 80% my_module.py 15 2 86% my_other_module.py 56 6 89%

TOTAL 91 12 87%

For each module executed, the report shows the count of executable statements, the number of those statements missed, and the resulting coverage, expressed as a percentage.

$ coverage report --help Usage: coverage report [options] [modules]

Report coverage statistics on modules.

Options: --contexts=REGEX1,REGEX2,... Only display data from lines covered in the given contexts. Accepts Python regexes, which must be quoted. --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --fail-under=MIN Exit with a status of 2 if the total coverage is less than MIN. --format=FORMAT Output format, either text (default), markdown, or total. -i, --ignore-errors Ignore errors while reading source files. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --precision=N Number of digits after the decimal point to display for reported coverage percentages. --sort=COLUMN Sort the report by the named column: name, stmts, miss, branch, brpart, or cover. Default is name. -m, --show-missing Show line numbers of statements in each module that weren't executed. --skip-covered Skip files with 100% coverage. --no-skip-covered Disable --skip-covered. --skip-empty Skip files with no code. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

The -m flag also shows the line numbers of missing statements:

$ coverage report -m Name Stmts Miss Cover Missing

my_program.py 20 4 80% 33-35, 39 my_module.py 15 2 86% 8, 12 my_other_module.py 56 6 89% 17-23

TOTAL 91 12 87%

If you are using branch coverage, then branch statistics will be reported in the Branch and BrPart (for Partial Branch) columns, the Missing column will detail the missed branches:

$ coverage report -m Name Stmts Miss Branch BrPart Cover Missing

my_program.py 20 4 10 2 80% 33-35, 36->38, 39 my_module.py 15 2 3 0 86% 8, 12 my_other_module.py 56 6 5 1 89% 17-23, 40->45

TOTAL 91 12 18 3 87%

Ranges of lines are shown with a dash: “17-23” means all lines from 17 to 23 inclusive are missing coverage. Missed branches are shown with an arrow: “40->45” means the branch from line 40 to line 45 is missing. A branch can go backwards in a file, so you might see a branch from a later line to an earlier line, like “55->50”.

You can restrict the report to only certain files by naming them on the command line:

$ coverage report -m my_program.py my_other_module.py 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%

The --skip-covered switch will skip any file with 100% coverage, letting you focus on the files that still need attention. The --no-skip-coveredoption can be used if needed to see all the files. The --skip-empty switch will skip any file with no executable statements.

If you have recorded contexts, the --contexts option lets you choose which contexts to report on. See Context reporting for details.

The --precision option controls the number of digits displayed after the decimal point in coverage percentages, defaulting to none.

The --sort option is the name of a column to sort the report by.

The --format option controls the style of the report. --format=textcreates plain text tables as shown above. --format=markdown creates Markdown tables. --format=total writes out a single number, the total coverage percentage as shown at the end of the tables, but without a percent sign.

Other common reporting options are described above in Reporting. These options can also be set in your .coveragerc file. SeeConfiguration: [report].

HTML reporting: coverage html

Coverage.py can annotate your source code to show which lines were executed and which were not. The html command creates an HTML report similar to thereport summary, but as an HTML file. Each module name links to the source file decorated to show the status of each line.

Here’s a sample report.

Lines are highlighted: green for executed, red for missing, and gray for excluded. If you’ve used branch coverage, partial branches are yellow. The colored counts at the top of the file are buttons to turn on and off the highlighting.

A number of keyboard shortcuts are available for navigating the report. Click the keyboard icon in the upper right to see the complete list.

$ coverage html --help Usage: coverage html [options] [modules]

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

Options: --contexts=REGEX1,REGEX2,... Only display data from lines covered in the given contexts. Accepts Python regexes, which must be quoted. -d DIR, --directory=DIR Write the output files to DIR. --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --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. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --precision=N Number of digits after the decimal point to display for reported coverage percentages. -q, --quiet Don't print messages about what is happening. --show-contexts Show contexts for covered lines. --skip-covered Skip files with 100% coverage. --no-skip-covered Disable --skip-covered. --skip-empty Skip files with no code. --title=TITLE A text string to use as the title on the HTML. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

The title of the report can be set with the title setting in the[html] section of the configuration file, or the --title switch on the command line.

If you prefer a different style for your HTML report, you can provide your own CSS file to apply, by specifying a CSS file in the [html] section of the configuration file. See [html] extra_css for details.

The -d argument specifies an output directory, defaulting to “htmlcov”:

$ coverage html -d coverage_html

Other common reporting options are described above in Reporting.

Generating the HTML report can be time-consuming. Stored with the HTML report is a data file that is used to speed up reporting the next time. If you generate a new report into the same directory, coverage.py will skip generating unchanged pages, making the process faster.

The --skip-covered switch will skip any file with 100% coverage, letting you focus on the files that still need attention. The --skip-empty switch will skip any file with no executable statements.

The --precision option controls the number of digits displayed after the decimal point in coverage percentages, defaulting to none.

If you have recorded contexts, the --contexts option lets you choose which contexts to report on, and the --show-contexts option will annotate lines with the contexts that ran them. See Context reportingfor details.

These options can also be set in your .coveragerc file. SeeConfiguration: [html].

XML reporting: coverage xml

The xml command writes coverage data to a “coverage.xml” file in a format compatible with Cobertura.

$ coverage xml --help Usage: coverage xml [options] [modules]

Generate an XML report of coverage results.

Options: --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --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. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -o OUTFILE Write the XML report to this file. Defaults to 'coverage.xml' -q, --quiet Don't print messages about what is happening. --skip-empty Skip files with no code. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

You can specify the name of the output file with the -o switch.

Other common reporting options are described above in Reporting.

To include complete file paths in the output file, rather than just the file name, use [include] vs [source] in your “.coveragerc” file.

For example, use this:

[run] include = foo/* bar/*

which will result in

in place of this:

which may result in

These options can also be set in your .coveragerc file. SeeConfiguration: [xml].

JSON reporting: coverage json

The json command writes coverage data to a “coverage.json” file.

$ coverage json --help Usage: coverage json [options] [modules]

Generate a JSON report of coverage results.

Options: --contexts=REGEX1,REGEX2,... Only display data from lines covered in the given contexts. Accepts Python regexes, which must be quoted. --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --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. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -o OUTFILE Write the JSON report to this file. Defaults to 'coverage.json' --pretty-print Format the JSON for human readers. -q, --quiet Don't print messages about what is happening. --show-contexts Show contexts for covered lines. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

You can specify the name of the output file with the -o switch. The JSON can be nicely formatted by specifying the --pretty-print switch.

Other common reporting options are described above in Reporting. These options can also be set in your .coveragerc file. SeeConfiguration: [json].

LCOV reporting: coverage lcov

The lcov command writes coverage data to a “coverage.lcov” file.

$ coverage lcov --help Usage: coverage lcov [options] [modules]

Generate an LCOV report of coverage results.

Options: --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] --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. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -o OUTFILE Write the LCOV report to this file. Defaults to 'coverage.lcov' --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. -q, --quiet Don't print messages about what is happening. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

Common reporting options are described above in Reporting. Also see Configuration: [lcov].

Added in version 6.3.

Text annotation: coverage annotate

Note

The annotate command has been obsoleted by more modern reporting tools, including the html command.

The annotate command produces a text annotation of your source code. With a -d argument specifying an output directory, each Python file becomes a text file in that directory. Without -d, the files are written into the same directories as the original Python files.

Coverage status for each line of source is indicated with a character prefix:

executed ! missing (not executed)

For example:

A simple function, never called with x==1

def h(x): """Silly function."""

if x == 1:

! a = 1 else: a = 2

$ coverage annotate --help Usage: coverage annotate [options] [modules]

Make annotated copies of the given files, marking statements that are executed with > and statements that are missed with !.

Options: -d DIR, --directory=DIR Write the output files to DIR. --data-file=INFILE Read coverage data for report generation from this file. Defaults to '.coverage'. [env: COVERAGE_FILE] -i, --ignore-errors Ignore errors while reading source files. --include=PAT1,PAT2,... Include only files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --omit=PAT1,PAT2,... Omit files whose paths match one of these patterns. Accepts shell-style wildcards, which must be quoted. --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

Other common reporting options are described above in Reporting.

Diagnostics: coverage debug

The debug command shows internal information to help diagnose problems. If you are reporting a bug about coverage.py, including the output of this command can often help:

$ coverage debug sys > please_attach_to_bug_report.txt

A few types of information are available:

$ coverage debug --help Usage: coverage debug

Display information about the internals of coverage.py, for diagnosing problems. Topics are: 'data' to show a summary of the collected data; 'sys' to show installation information; 'config' to show the configuration; 'premain' to show what is calling coverage; 'pybehave' to show internal flags describing Python behavior.

Options: --debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG] -h, --help Get help on this command. --rcfile=RCFILE Specify configuration file. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. [env: COVERAGE_RCFILE]

--debug

The --debug option is also available on all commands. It instructs coverage.py to log internal details of its operation, to help with diagnosing problems. It takes a comma-separated list of options, each indicating a facet of operation to log:

Debug options can also be set with the COVERAGE_DEBUG environment variable, a comma-separated list of these options, or in the [run] debugsection of the .coveragerc file.

The debug output goes to stderr, unless the [run] debug_filesetting or the COVERAGE_DEBUG_FILE environment variable names a different file, which will be appended to. This can be useful because many test runners capture output, which could hide important details. COVERAGE_DEBUG_FILEaccepts the special names stdout and stderr to write to those destinations.