Configuration reference

Coverage.py options can be specified in a configuration file. This makes it easier to re-run coverage.py with consistent settings, and also allows for specification of options that are otherwise only available in the API.

Configuration files also make it easier to get coverage testing of spawned sub-processes. See Measuring sub-processes for more details.

The default name for configuration files is .coveragerc, in the same directory coverage.py is being run in. Most of the settings in the configuration file are tied to your source code and how it should be measured, so it should be stored with your source, and checked into source control, rather than put in your home directory.

A different location for the configuration file can be specified with the --rcfile=FILE command line option or with the COVERAGE_RCFILE environment variable.

Coverage.py will read settings from other usual configuration files if no other configuration file is used. It will automatically read from “setup.cfg” or “tox.ini” if they exist. In this case, the section names have “coverage:” prefixed, so the [run] options described below will be found in the [coverage:run] section of the file. If coverage.py is installed with the toml extra (pip install coverage[toml]), it will automatically read from “pyproject.toml”. Configuration must be within the [tool.coverage] section, for example, [tool.coverage.run].

Syntax

A coverage.py configuration file is in classic .ini file format: sections are introduced by a [section] header, and contain name = value entries. Lines beginning with # or ; are ignored as comments.

Strings don’t need quotes. Multi-valued strings can be created by indenting values on multiple lines.

Boolean values can be specified as on, off, true, false, 1, or 0 and are case-insensitive.

Environment variables can be substituted in by using dollar signs: $WORD or ${WORD} will be replaced with the value of WORD in the environment. A dollar sign can be inserted with $$. Special forms can be used to control what happens if the variable isn’t defined in the environment:

If you want to raise an error if an environment variable is undefined, use a question mark suffix: ${WORD?}.
If you want to provide a default for missing variables, use a dash with a default value: ${WORD-default value}.
Otherwise, missing environment variables will result in empty strings with no error.

Many sections and settings correspond roughly to commands and options in the command-line interface.

Here’s a sample configuration file:

# .coveragerc to control coverage.py
[run]
branch = True

[report]
# Regexes for lines to exclude from consideration
exclude_lines =
    # Have to re-enable the standard pragma
    pragma: no cover

    # Don't complain about missing debug-only code:
    def __repr__
    if self\.debug

    # Don't complain if tests don't hit defensive assertion code:
    raise AssertionError
    raise NotImplementedError

    # Don't complain if non-runnable code isn't run:
    if 0:
    if __name__ == .__main__.:

    # Don't complain about abstract methods, they aren't run:
    @(abc\.)?abstractmethod

ignore_errors = True

[html]
directory = coverage_html_report

[run]

These settings are generally used when running product code, though some apply to more than one command.

[run] branch

(boolean, default False) Whether to measure branch coverage in addition to statement coverage.

[run] command_line

(string) The command-line to run your program. This will be used if you run coverage run with no further arguments. Coverage.py options cannot be specified here, other than -m to indicate the module to run.

New in version 5.0.

[run] concurrency

(multi-string, default “thread”) The concurrency libraries in use by the product code. If your program uses multiprocessing, gevent, greenlet, or eventlet, you must name that library in this option, or coverage.py will produce very wrong results.

See Measuring sub-processes for details of multi-process measurement.

Before version 4.2, this option only accepted a single string.

New in version 4.0.

[run] context

(string) The static context to record for this coverage run. See Measurement contexts for more information

New in version 5.0.

[run] cover_pylib

(boolean, default False) Whether to measure the Python standard library.

[run] data_file

(string, default “.coverage”) The name of the data file to use for storing or reporting coverage. This value can include a path to another directory.

[run] disable_warnings

(multi-string) A list of warnings to disable. Warnings that can be disabled include a short string at the end, the name of the warning. See Warnings for specific warnings.

[run] debug

(multi-string) A list of debug options. See the run –debug option for details.

[run] dynamic_context

(string) The name of a strategy for setting the dynamic context during execution. See Dynamic contexts for details.

[run] include

(multi-string) A list of file name patterns, the files to include in measurement or reporting. Ignored if source is set. See Specifying source files for details.

[run] note

(string) This is now obsolete.

[run] omit

(multi-string) A list of file name patterns, the files to leave out of measurement or reporting. See Specifying source files for details.

[run] parallel

(boolean, default False) Append the machine name, process id and random number to the data file name to simplify collecting data from many processes. See Combining data files: coverage combine for more information.

[run] plugins

(multi-string) A list of plugin package names. See Plug-ins for more information.

[run] relative_files

(experimental, boolean, default False) store relative file paths in the data file. This makes it easier to measure code in one (or multiple) environments, and then report in another. See Combining data files: coverage combine for details.

Note that setting source has to be done in the configuration file rather than the command line for this option to work, since the reporting commands need to know the source origin.

New in version 5.0.

[run] sigterm

(boolean, default False) if true, register a SIGTERM signal handler to capture data when the process ends due to a SIGTERM signal. This includes Process.terminate, and other ways to terminate a process. This can help when collecting data in usual situations, but can also introduce problems (see issue 1310).

Only on Linux and Mac.

New in version 6.4: (in 6.3 this was always enabled)

[run] source

(multi-string) A list of packages or directories, the source to measure during execution. If set, include is ignored. See Specifying source files for details.

[run] source_pkgs

(multi-string) A list of packages, the source to measure during execution. Operates the same as source, but only names packages, for resolving ambiguities between packages and directories.

New in version 5.3.

[run] timid

(boolean, default False) Use a simpler but slower trace method. This uses PyTracer instead of CTracer, and is only needed in very unusual circumstances. Try this if you get seemingly impossible results.

[paths]

The entries in this section are lists of file paths that should be considered equivalent when combining data from different machines:

[paths]
source =
    src/
    /jenkins/build/*/src
    c:\myproj\src

The names of the entries (“source” in this example) are ignored, you may choose any name that you like. The value is a list of strings. When combining data with the combine command, two file paths will be combined if they start with paths from the same list.

The first value must be an actual file path on the machine where the reporting will happen, so that source code can be found. The other values can be file patterns to match against the paths of collected data, or they can be absolute or relative file paths on the current machine.

In this example, data collected for “/jenkins/build/1234/src/module.py” will be combined with data for “c:\myproj\src\module.py”, and will be reported against the source file found at “src/module.py”.

If you specify more than one list of paths, they will be considered in order. The first list that has a match will be used.

The --debug=pathmap option can be used to log details of the re-mapping of paths. See the –debug option.

See Combining data files: coverage combine for more information.

[report]

Settings common to many kinds of reporting.

[report] exclude_lines

(multi-string) A list of regular expressions. Any line of your source code containing a match for one of these regexes is excluded from being reported as missing. More details are in Excluding code from coverage.py. If you use this option, you are replacing all the exclude regexes, so you’ll need to also supply the “pragma: no cover” regex if you still want to use it.

You can exclude lines introducing blocks, and the entire block is excluded. If you exclude a def line or decorator line, the entire function is excluded.

Be careful when writing this setting: the values are regular expressions that only have to match a portion of the line. For example, if you write ..., you’ll exclude any line with three or more of any character. If you write pass, you’ll also exclude the line my_pass="foo", and so on.

[report] fail_under

(float) A target coverage percentage. If the total coverage measurement is under this value, then exit with a status code of 2. If you specify a non-integral value, you must also set [report] precision properly to make use of the decimal places. A setting of 100 will fail any value under 100, regardless of the number of decimal places of precision.

[report] ignore_errors

(boolean, default False) Ignore source code that can’t be found, emitting a warning instead of an exception.

[report] include

(multi-string) A list of file name patterns, the files to include in reporting. See Specifying source files for details.

[report] omit

(multi-string) A list of file name patterns, the files to leave out of reporting. See Specifying source files for details.

[report] partial_branches

(multi-string) A list of regular expressions. Any line of code that matches one of these regexes is excused from being reported as a partial branch. More details are in Branch coverage measurement. If you use this option, you are replacing all the partial branch regexes so you’ll need to also supply the “pragma: no branch” regex if you still want to use it.

[report] precision

(integer) The number of digits after the decimal point to display for reported coverage percentages. The default is 0, displaying for example “87%”. A value of 2 will display percentages like “87.32%”. This setting also affects the interpretation of the fail_under setting.

[report] show_missing

(boolean, default False) When running a summary report, show missing lines. See Coverage summary: coverage report for more information.

[report] skip_covered

(boolean, default False) Don’t report files that are 100% covered. This helps you focus on files that need attention.

[report] skip_empty

(boolean, default False) Don’t report files that have no executable code (such as __init__.py files).

[report] sort

(string, default “Name”) Sort the text report by the named column. Allowed values are “Name”, “Stmts”, “Miss”, “Branch”, “BrPart”, or “Cover”. Prefix with - for descending sort (for example, “-cover”).

[html]

Settings particular to HTML reporting. The settings in the [report] section also apply to HTML output, where appropriate.

[html] directory

(string, default “htmlcov”) Where to write the HTML report files.

[html] extra_css

(string) The path to a file of CSS to apply to the HTML report. The file will be copied into the HTML output directory. Don’t name it “style.css”. This CSS is in addition to the CSS normally used, though you can overwrite as many of the rules as you like.

[html] show_contexts

(boolean) Should the HTML report include an indication on each line of which contexts executed the line. See Dynamic contexts for details.

[html] skip_covered

(boolean, defaulted from [report] skip_covered) Don’t include files in the report that are 100% covered files. See Coverage summary: coverage report for more information.

New in version 5.4.

[html] skip_empty

(boolean, defaulted from [report] skip_empty) Don’t include empty files (those that have 0 statements) in the report. See Coverage summary: coverage report for more information.

New in version 5.4.

[html] title

(string, default “Coverage report”) The title to use for the report. Note this is text, not HTML.

[xml]

Settings particular to XML reporting. The settings in the [report] section also apply to XML output, where appropriate.

[xml] output

(string, default “coverage.xml”) Where to write the XML report.

[xml] package_depth

(integer, default 99) Controls which directories are identified as packages in the report. Directories deeper than this depth are not reported as packages. The default is that all directories are reported as packages.

[json]

Settings particular to JSON reporting. The settings in the [report] section also apply to JSON output, where appropriate.

New in version 5.0.

[json] output

(string, default “coverage.json”) Where to write the JSON file.

[json] pretty_print

(boolean, default false) Controls if the JSON is outputted with whitespace formatted for human consumption (True) or for minimum file size (False).

[json] show_contexts

(boolean, default false) Should the JSON report include an indication of which contexts executed each line. See Dynamic contexts for details.

[lcov]

Settings particular to LCOV reporting (see LCOV reporting: coverage lcov).

New in version 6.3.

[lcov] output

(string, default “coverage.lcov”) Where to write the LCOV file.