New in version 4.0.’s behavior can be extended with third-party plugins. A plugin is a separately installed Python class that you register in your .coveragerc. Plugins can be used to implement coverage measurement for non-Python files.

Using plugins

To use a plugin, you install it, and configure it. For this example, let’s say there’s a Python package called something that provides a plugin called something.plugin.

  1. Install the plugin’s package as you would any other Python package:

    pip install something
  2. Configure to use the plugin. You do this by editing (or creating) your .coveragerc file, as described in Configuration files. The plugins setting indicates your plugin. It’s a list of importable module names of plugins:

    plugins =
  3. If the plugin needs its own configuration, you can add those settings in the .coveragerc file in a section named for the plugin:

    option1 = True
    option2 =

    Check the documentation for the plugin to see if it takes any options, and what they are.

  4. Run your tests as you usually would.

Plugin API

class coverage.CoveragePlugin

Base class for plugins.

To write a plugin, create a module with a subclass of CoveragePlugin. You can override methods in your class to participate in various aspects of’s processing.

Currently the only plugin type is a file tracer, for implementing measurement support for non-Python files. File tracer plugins implement the file_tracer() method to claim files and the file_reporter() method to report on those files.

Any plugin can optionally implement sys_info() to provide debugging information about their operation. will store its own information on your plugin, with attributes starting with “_coverage_”. Don’t be startled.

To register your plugin, define a function called coverage_init in your module:

def coverage_init(reg, options):

The reg.add_file_tracer method takes an instance of your plugin. If your plugin takes options, the options argument is a dictionary of your plugin’s options from the .coveragerc file.


Return the FileReporter class to use for filename.

This will only be invoked if filename returns non-None from file_tracer(). It’s an error to return None.


Return a FileTracer object for a file.

Every source file is offered to the plugin to give it a chance to take responsibility for tracing the file. If your plugin can handle the file, then return a FileTracer object. Otherwise return None.

There is no way to register your plugin for particular files. Instead, this method is invoked for all files, and can decide whether it can trace the file or not. Be prepared for filename to refer to all kinds of files that have nothing to do with your plugin.

filename is a string, the path to the file being considered. This is the absolute real path to the file. If you are comparing to other paths, be sure to take this into account.

Returns a FileTracer object to use to trace filename, or None if this plugin cannot trace this file.


Return a list of information useful for debugging.

This method will be invoked for --debug=sys. Your plugin can return any information it wants to be displayed.

The return value is a list of pairs: (name, value).

class coverage.FileTracer

Support needed for files during the tracing phase.

You may construct this object from CoveragePlugin.file_tracer() any way you like. A natural choice would be to pass the filename given to file_tracer.

dynamic_source_filename(filename, frame)

Returns a dynamically computed source filename.

Some plugins need to compute the source filename dynamically for each frame.

This function will not be invoked if has_dynamic_source_filename() returns False.

Returns the source filename for this frame, or None if this frame shouldn’t be measured.


Does this FileTracer have dynamic source filenames?

FileTracers can provide dynamically determined filenames by implementing dynamic_source_filename. Invoking that function is expensive. To determine whether to invoke it, uses the result of this function to know if it needs to bother invoking dynamic_source_filename().

Returns true if dynamic_source_filename() should be called to get dynamic source filenames.


Return the range of source line numbers for a given a call frame.

The call frame is examined, and the source line number in the original file is returned. The return value is a pair of numbers, the starting line number and the ending line number, both inclusive. For example, returning (5, 7) means that lines 5, 6, and 7 should be considered executed.

This function might decide that the frame doesn’t indicate any lines from the source file were executed. Return (-1, -1) in this case to tell that no lines should be recorded for this frame.


The source filename for this file.

This may be any filename you like. A key responsibility of a plugin is to own the mapping from Python execution back to whatever source filename was originally the source of the code.

Returns the filename to credit with this execution.

class coverage.FileReporter(filename)

Support needed for files during the reporting phase.


A base for a flat filename to correspond to this file.

Useful for writing files about the code where you want all the files in the same directory, but need to differentiate same-named files from different directories.

For example, the file a/b/ will return ‘a_b_c_py’

You should not need to override this method.


Does it seem like this file should contain Python?

This is used to decide if a file reported as part of the execution of a program was really likely to have contained Python in the first place.


Return the source for the code, a Unicode string.


Return the ‘tokenized’ text for the code.