{"id":3437,"library":"coveralls","title":"Coveralls Python","description":"Coveralls Python (coveralls-python) is a Python library that provides seamless integration with coverage.py to send code coverage statistics to Coveralls.io. It supports various Continuous Integration (CI) systems and allows for detailed online reporting of test coverage for Python projects. Currently at version 4.1.0, it is actively maintained with several releases per year to keep up with Python and `coverage.py` updates.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/TheKevJames/coveralls-python","tags":["coverage","testing","ci","code quality","coveralls.io"],"install":[{"cmd":"pip install coveralls","lang":"bash","label":"Basic installation"},{"cmd":"pip install coveralls[yaml]","lang":"bash","label":"For .coveralls.yml configuration"}],"dependencies":[{"reason":"Required for collecting code coverage data.","package":"coverage","optional":false},{"reason":"Required for reading configuration from a .coveralls.yml file.","package":"pyyaml","optional":true},{"reason":"Used for the command-line interface; replaced 'docopt' in 4.1.0.","package":"typer","optional":false}],"imports":[],"quickstart":{"code":"import os\n\n# Simulate running tests with coverage.py\n# In a real scenario, you'd run your tests like:\n# coverage run -m pytest\n# For this example, we assume coverage.py has already generated .coverage data.\n\n# Set the Coveralls repository token (replace with your actual token or use env var)\n# This is often handled automatically in supported CI environments.\n# For local testing or unsupported CIs, ensure COVERALLS_REPO_TOKEN is set.\n# You can find this token on your project's dashboard in coveralls.io.\nos.environ['COVERALLS_REPO_TOKEN'] = os.environ.get('COVERALLS_REPO_TOKEN', 'your_coveralls_repo_token_here')\n\n# Run the coveralls command-line tool\nimport subprocess\ntry:\n    # Typically, you'd run 'coverage run -m pytest' first, then 'coveralls'\n    # For this example, we simulate the submission step after coverage data is assumed to exist.\n    print(\"Attempting to submit coverage to Coveralls.io...\")\n    # The actual command would be: subprocess.run([\"coveralls\"], check=True)\n    # We'll mock the output for a runnable example without actual submission.\n    mock_output = \"Submitting coverage to coveralls.io...\\nCoverage submitted! Job #123.456 https://coveralls.io/jobs/1234567890\"\n    print(mock_output)\n    # For an actual run:\n    # result = subprocess.run([\"coveralls\"], capture_output=True, text=True, check=True)\n    # print(result.stdout)\n    # print(result.stderr)\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error submitting coverage: {e.stderr}\")\nexcept FileNotFoundError:\n    print(\"Error: 'coveralls' command not found. Ensure coveralls is installed and in your PATH.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Review your `coverage.py` configuration (e.g., `.coveragerc`) for the `ignore_errors` setting and adjust if you relied on the previous error-muting behavior.","message":"In 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review all your configuration sources (CI settings, environment variables, `.coveralls.yml`, CLI flags) and ensure they produce the desired outcome under the new precedence rules.","message":"In 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consider 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.","message":"For 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.","severity":"gotcha","affected_versions":"All versions with Python 3.13+ and/or coverage.py v7+"},{"fix":"Always 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.","message":"The `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+.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Obtain 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]`).","message":"The `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.","severity":"gotcha","affected_versions":"All versions (outside of specific CI environments)"},{"fix":"Add `relative_files = True` to your `coverage.py` configuration file. For `pyproject.toml`, ensure `coverage[toml]` is installed.","message":"To 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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade 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.","message":"Python 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.","severity":"deprecated","affected_versions":"<4.0.2 (for Python 3.8/3.9), <3.x (for older Python versions)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}