Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
After installing `coveralls` and collecting coverage data with `coverage.py` (e.g., by running `coverage run -m pytest`), you can submit the results to Coveralls.io. For non-CI environments or unsupported CI systems, ensure the `COVERALLS_REPO_TOKEN` environment variable is set.
import os
# Simulate running tests with coverage.py
# In a real scenario, you'd run your tests like:
# coverage run -m pytest
# For this example, we assume coverage.py has already generated .coverage data.
# Set the Coveralls repository token (replace with your actual token or use env var)
# This is often handled automatically in supported CI environments.
# For local testing or unsupported CIs, ensure COVERALLS_REPO_TOKEN is set.
# You can find this token on your project's dashboard in coveralls.io.
os.environ['COVERALLS_REPO_TOKEN'] = os.environ.get('COVERALLS_REPO_TOKEN', 'your_coveralls_repo_token_here')
# Run the coveralls command-line tool
import subprocess
try:
# Typically, you'd run 'coverage run -m pytest' first, then 'coveralls'
# For this example, we simulate the submission step after coverage data is assumed to exist.
print("Attempting to submit coverage to Coveralls.io...")
# The actual command would be: subprocess.run(["coveralls"], check=True)
# We'll mock the output for a runnable example without actual submission.
mock_output = "Submitting coverage to coveralls.io...\nCoverage submitted! Job #123.456 https://coveralls.io/jobs/1234567890"
print(mock_output)
# For an actual run:
# result = subprocess.run(["coveralls"], capture_output=True, text=True, check=True)
# print(result.stdout)
# print(result.stderr)
except subprocess.CalledProcessError as e:
print(f"Error submitting coverage: {e.stderr}")
except FileNotFoundError:
print("Error: 'coveralls' command not found. Ensure coveralls is installed and in your PATH.")
coveralls --version
Debug
Known issues
breakingIn version 4.0.0, the behavior of `config.ignore_errors` changed. When `config.ignore_errors` is Falsey, failures to parse Python files or look up file sources will now interrupt and early exit collection, matching default `coverage.py` behavior. Previously, these errors were manually muted or only reported after collecting multiple failures.fixReview your `coverage.py` configuration (e.g., `.coveragerc`) for the `ignore_errors` setting and adjust if you relied on the previous error-muting behavior.
affects: >=4.0.0
breakingIn version 3.0.0, the configuration precedence was reversed. The new order (latest value used) is: CI Config, `COVERALLS_*` env vars, `.coveralls.yml` file, CLI flags. If you have the same fields set in multiple locations, verify your configuration after upgrading.fixReview all your configuration sources (CI settings, environment variables, `.coveralls.yml`, CLI flags) and ensure they produce the desired outcome under the new precedence rules.
affects: >=3.0.0
gotchaFor Python 3.13+ and `coverage.py` v7+, the official Coveralls documentation recommends switching to their GitHub Action, CircleCI Orb, or Universal Coverage Reporter CLI tool, as direct `coveralls-python` integration may have lapsed support for the latest `coverage.py` formats.fixConsider migrating to an officially maintained Coveralls integration (e.g., GitHub Action) if you encounter issues with newer Python or `coverage.py` versions. Generate Cobertura XML reports with `coverage xml` and submit them via the official tools.
affects: All versions with Python 3.13+ and/or coverage.py v7+
gotchaThe `coveralls` package depends on `coverage.py`. There have been known incompatibilities with specific `coverage.py` versions (e.g., v6.0.0-v6.1.1 were excluded in `coveralls` v3.3.1). Ensure you are using compatible versions of both libraries. `coveralls` v4.0.1 specifically added support for `coverage` v7.5+.fixAlways install the latest `coveralls` version. If encountering issues, consult the `coveralls-python` and `coverage.py` release notes for compatibility details and ensure your `coverage.py` version is supported.
affects: All versions
gotchaThe `COVERALLS_REPO_TOKEN` environment variable (or `repo_token` in `.coveralls.yml`) is crucial for submitting coverage data outside of officially supported CI environments like TravisCI or GitHub Actions. Without it, submissions will fail.fixObtain your repository token from Coveralls.io and set it as an environment variable `COVERALLS_REPO_TOKEN` before running the `coveralls` command. Alternatively, configure it in a `.coveralls.yml` file (requires `coveralls[yaml]`).
affects: All versions (outside of specific CI environments)
gotchaTo avoid 'not a git repository' errors, particularly in CI environments, ensure `relative_files = True` is configured in your `coverage.py` configuration (e.g., in the `[run]` section of `.coveragerc`, `setup.cfg`, `tox.ini`, or `[tool.coverage.run]` in `pyproject.toml`).fixAdd `relative_files = True` to your `coverage.py` configuration file. For `pyproject.toml`, ensure `coverage[toml]` is installed.
affects: All versions
deprecatedPython 3.8 and 3.9 support was dropped in `coveralls` v4.0.2. Earlier versions dropped support for Python 3.7 and below, and Python 2.7/3.4.fixUpgrade to a supported Python version (>=3.10) for `coveralls` 4.x. If you must use older Python versions, pin `coveralls` to a compatible older version.
affects: <4.0.2 (for Python 3.8/3.9), <3.x (for older Python versions)
Errors
Common errors & fixes
422 Client Error: Unprocessable Entity for url: https://coveralls.io/api/v1/jobs
This error, often accompanied by 'Couldn't find a repository matching this job,' indicates that the Coveralls API could not link the incoming coverage report to an existing repository, usually due to a missing, incorrect, or expired `COVERALLS_REPO_TOKEN`, or a misconfigured `service_name` in CI environments.
fixEnsure the `COVERALLS_REPO_TOKEN` environment variable is correctly set in your CI configuration with the exact token from your Coveralls.io repository settings. For GitHub Actions, confirm `GITHUB_TOKEN` is passed correctly and consider setting `COVERALLS_SERVICE_NAME: github-actions` in your `.coveralls.yml` or as an environment variable.
My build shows 0%, but I know I have some coverage.
Coveralls reports 0% coverage when it successfully receives a coverage report but cannot locate the referenced source files within your repository, often due to mismatched file paths between the coverage report and the Git tree, or if the `source_files` array in the JSON payload is empty.
fixVerify that your `coverage.py` report (e.g., `.coverage` file or `lcov.info`) is generated in the expected location relative to your repository's root, and that the paths within the report correctly map to your source files. For GitHub Actions, use the `base-path` input option of the Coveralls GitHub Action to adjust file paths if needed.
ImportError: cannot import name 'Reporter' from 'coverage.report'
This `ImportError` (or similar errors like `cannot import name 'FnmatchMatcher'` or `TypeError: Reporter() takes no arguments`) typically occurs due to an incompatibility between the installed version of `coveralls-python` and newer, incompatible versions of `coverage.py` (e.g., `coverage.py` v6 or v7+ introduces breaking changes to its internal API).
fixUpdate `coveralls-python` to its latest version (`pip install --upgrade coveralls`) to ensure compatibility with recent `coverage.py` versions. If the issue persists, consider pinning `coverage.py` to an older, compatible version (e.g., `coverage<6`) or switch to an officially maintained integration that uses standard report formats like Cobertura XML.
ModuleNotFoundError: No module named 'coveralls.cli'
This error means that the Python interpreter cannot find the `coveralls.cli` module, indicating that the `coveralls` package is either not installed in the active environment, installed incorrectly, or there's a conflict with an old or different `coveralls` package (e.g., `python-coveralls`).
fixEnsure `coveralls` is installed in your current Python environment by running `pip install coveralls`. If you suspect conflicts, uninstall any existing `coveralls` or `python-coveralls` packages (`pip uninstall coveralls python-coveralls`) and then reinstall only `coveralls`.
Upgrade
Version history
4.1.0latest on PyPI · released Feb 28, 2026
Audit
Dependencies
coveragerequiredRequired for collecting code coverage data.
pyyamloptionalRequired for reading configuration from a .coveralls.yml file.
typerrequiredUsed for the command-line interface; replaced 'docopt' in 4.1.0.