Install & Compatibility
Where this runs
tested against v8.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 42.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.000s · 43MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gcovr
✓ gcovr
Gcovr is primarily a command-line tool. Direct programmatic imports for general use are not common. Its Python entry point is `gcovr.__main__.py` for CLI execution.
This quickstart demonstrates the typical workflow for using gcovr: compiling your C/C++ code with GCC's coverage flags, executing your program to generate coverage data, and then running the `gcovr` command-line tool to produce a human-readable report (e.g., HTML).
# 1. Create a sample C++ file (example.cpp)
#include <iostream>
int foo(int param) {
if (param) {
return 1;
} else {
return 0;
}
}
int main() {
foo(0);
std::cout << "Hello from main!" << std::endl;
return 0;
}
# 2. Compile the code with coverage flags
g++ -fprofile-arcs -ftest-coverage -O0 example.cpp -o program
# 3. Run the compiled program to generate .gcda data files
./program
# 4. Generate a coverage report using gcovr (e.g., HTML report)
gcovr -r . --html --html-details -o coverage.html
# To view the report:
# open coverage.html
gcovr --version
Debug
Known issues
breakingGcovr versions have dropped support for older Python versions. Version 7.0 dropped support for Python 3.7, and version 5.1 dropped Python 3.6 support. Version 5.0 removed support for Python 2 and Python 3.5.fixEnsure your environment uses Python 3.10 or newer for gcovr 8.x. Check gcovr's documentation for specific Python version requirements for older gcovr releases.
affects: <7.0 (for Python 3.7), <5.1 (for Python 3.6), <5.0 (for Python 2/3.5)
breakingExit codes for errors in the reader or writer modules have changed. In gcovr 7.0, a reader error's exit code changed from 8 to 64, and a writer error's from 7 to 128.fixUpdate any scripts or CI/CD pipelines that rely on gcovr's specific error exit codes to reflect the new values.
affects: >=7.0
gotchaForgetting to recompile your C/C++ code with coverage flags (`-fprofile-arcs -ftest-coverage` or `--coverage`) after making changes, or not cleaning old object files, can lead to outdated or incorrect coverage data. Also, using `-O` optimization flags can sometimes obscure coverage information.fixAlways perform a `make clean` or equivalent to clear old object files before recompiling with coverage flags. Compile with `-O0` (no optimization) for the most accurate coverage reports. For robust path handling, consider `-fprofile-abs-path` (GCC 8+).
affects: All
gotchaGcovr relies on the `gcov` executable. If you have multiple GCC/Clang versions or custom installations, `gcovr` might pick the wrong `gcov` by default, leading to parsing errors or incorrect reports.fixExplicitly specify the correct `gcov` executable using the `--gcov-executable` option (e.g., `--gcov-executable 'llvm-cov gcov'` for Clang or `gcovr --gcov-executable gcov-8`).
affects: All
gotchaOn Windows, issues with path separators (backslashes vs. forward slashes) and symlinks can cause `gcovr` to fail to find source files or generate detailed reports, especially when source files are in different directories from the build output.fixWhen using `--root` and filters, ensure paths are consistent. Consider using forward slashes even on Windows for filters. Ensure build systems handle paths correctly or run `gcovr` from the build directory with `--root ..`.
affects: All
breakingThe internal data model for coverage information per line was improved in version 8.x. This removed the `function return count` from internal data model, HTML, and JSON output, and `function_name` for a line in JSON report is now always set.fixIf you parse gcovr's JSON or XML reports programmatically, review your parsing logic to adapt to these data model changes and the new structure for function coverage.
affects: >=8.x
Upgrade
Version history
8.6latest on PyPI · released Jan 13, 2026
Audit
Dependencies
gcc/g++requiredRequired to compile C/C++ code with coverage instrumentation.
gcovrequiredThe underlying utility that generates raw coverage data; gcovr processes its output.