{"id":10159,"library":"python-coveralls","title":"Coveralls Python","description":"python-coveralls is a Python interface to the coveralls.io API, enabling continuous integration services to send test coverage reports for Python projects. It integrates with `coverage.py` to process coverage data and send it to Coveralls.io. The current version is 2.9.3, and releases are generally made to address `coverage.py` compatibility, Python version support, or minor bug fixes, rather than on a fixed cadence.","status":"active","version":"2.9.3","language":"en","source_language":"en","source_url":"https://github.com/z4r/python-coveralls","tags":["code coverage","CI/CD","testing"],"install":[{"cmd":"pip install python-coveralls","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"Required to generate coverage data files (.coverage) that python-coveralls processes.","package":"coverage","optional":false}],"imports":[{"note":"While a `Coveralls` class exists, direct import and use in user application code is uncommon. The library is primarily used via its command-line interface (`coveralls`).","symbol":"Coveralls","correct":"from coveralls import Coveralls"}],"quickstart":{"code":"# 1. Install necessary packages\npip install coverage python-coveralls\n\n# 2. Run your tests with coverage.py to generate .coverage data\n#    Replace 'pytest' with your actual test runner (e.g., 'python -m unittest discover')\n#    Replace 'your_module_name' with the actual name of your package/module to cover\ncoverage run --source=your_module_name -m pytest\n\n# 3. Send the coverage report to Coveralls.io\n#    Set your repository token as an environment variable.\n#    In CI environments (e.g., GitHub Actions, Travis CI), this is often handled automatically\n#    or provided securely. For local testing, ensure it's exported in your shell.\n#    Using a placeholder; replace with your actual token.\nexport COVERALLS_REPO_TOKEN='YOUR_ACTUAL_COVERALLS_REPO_TOKEN'\n\n#    Now run the coveralls command-line tool\ncoveralls","lang":"bash","description":"This quickstart demonstrates the typical workflow: first, generate coverage data using `coverage.py` after running your tests, and then use the `coveralls` command-line tool to send the `.coverage` report to Coveralls.io. Ensure the `COVERALLS_REPO_TOKEN` is set, especially in CI environments."},"warnings":[{"fix":"Always run your tests with `coverage run` (e.g., `coverage run --source=your_package -m pytest`) before invoking `coveralls`. Verify a `.coverage` file is created and contains data.","message":"python-coveralls relies on `coverage.py` to generate the `.coverage` data file. If this file is missing, empty, or not found in the expected location, `coveralls` will report 'No coverage data found'.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `COVERALLS_REPO_TOKEN` in your CI environment or locally (e.g., `export COVERALLS_REPO_TOKEN=YOUR_TOKEN`). For CI services, sometimes `CI` environment variables are sufficient, but providing the token is the most robust approach.","message":"A `COVERALLS_REPO_TOKEN` environment variable or a `.coveralls.yml` file with a `repo_token` is required for authentication with Coveralls.io. Without it, the report will fail to upload.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your project to Python 3 or pin `python-coveralls` to a version less than 2.0.0 (e.g., `pip install python-coveralls==1.11.0`).","message":"Python 2 support was dropped in version 2.0.0. Projects using Python 2 must use `python-coveralls<2.0.0`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the command runs in a Git repository context, or explicitly provide git details via environment variables (e.g., `COVERALLS_BRANCH`) or a `.coveralls.yml` configuration file.","message":"The `coveralls` command can fail to detect repository details (like branch name) if executed outside of a recognized CI environment or a Git repository, leading to `KeyError` or incomplete reports.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `coverage run --source=your_module_name ...` is executed before `coveralls`. Verify a `.coverage` file exists and contains data.","cause":"The `coverage.py` tool was not run, or it did not generate a `.coverage` file in the expected location, or the file was empty.","error":"No coverage data found."},{"fix":"Set the `COVERALLS_REPO_TOKEN` environment variable in your CI configuration or shell, or create a valid `.coveralls.yml` file in your project root with the token.","cause":"The `COVERALLS_REPO_TOKEN` environment variable was not set, or the `.coveralls.yml` file was missing/incorrect.","error":"Not authenticated. Have you provided a repo_token?"},{"fix":"Ensure CI environment variables are correctly propagated, or manually provide git details via `.coveralls.yml` or specific environment variables like `COVERALLS_BRANCH`, `COVERALLS_COMMIT`.","cause":"This often happens when Coveralls cannot automatically detect CI environment variables (e.g., `TRAVIS`, `GITHUB_ACTIONS`) and crucial git information like 'branch' is missing.","error":"KeyError: 'branch'"}]}