Codecov Python Uploader

2.1.13 · deprecated · verified Sat Apr 11

The `codecov` Python package provides a command-line interface for uploading code coverage reports to the Codecov.io platform. It integrates with various CI/CD services and testing tools to provide hosted coverage analytics for GitHub, Bitbucket, and GitLab repositories. Currently at version 2.1.13, this specific Python uploader is deprecated in favor of a universal Codecov CLI or GitHub Action, and its release cadence is irregular due to past deprecation and re-instatement events.

Warnings

breaking The `codecov-python` uploader is officially deprecated by Codecov. Users are strongly recommended to migrate to the universal Codecov CLI (binary uploader) or the Codecov GitHub Action. Continued use of this Python package may lead to future unannounced breakages or a complete cessation of functionality.
Fix: Migrate to the Codecov CLI (downloadable binary) or integrate the `codecov/codecov-action` for GitHub Actions. Refer to the official Codecov documentation for migration guides.
breaking In April 2023, the `codecov` package was abruptly removed from PyPI, causing widespread build failures for users before it was re-instated as version 2.1.13 with a deprecation notice. This incident highlighted the instability and deprecated status of the package.
Fix: While the package has been re-instated, the incident underscores the need to migrate away from this deprecated uploader to avoid similar, potentially permanent, future disruptions.
gotcha Users have reported inconsistent and unreliable behavior with the Python uploader over time, including random missed coverage, failures to upload reports (e.g., EPIPE errors), and issues with status reporting back to CI systems. This can lead to flaky CI builds and distrust in coverage metrics.
Fix: Consider migrating to the Codecov CLI or GitHub Action, which are actively maintained and designed to be more robust. Ensure your CI setup is stable and network connectivity to Codecov is consistent.
gotcha Incorrect or missing upload tokens, especially for private repositories, will prevent coverage data from being successfully uploaded and processed. Additionally, issues can arise if base or head commits lack coverage reports, or if file paths in the coverage report do not correctly map to the repository structure, leading to 'missing base report' or 'unusable report' errors.
Fix: Always provide the `CODECOV_TOKEN` for private repositories (e.g., `codecov -t $CODECOV_TOKEN`). Ensure your CI workflow always generates and uploads coverage reports for all relevant commits (both base and head of a PR) and that file paths are consistent. Consult Codecov's troubleshooting guides for path fixing.

Install

pip install codecov Install via pip

Imports

codecov
```
codecov -t $CODECOV_TOKEN
```
The `codecov` PyPI package is primarily a console script, not a library intended for direct Python import for its main upload functionality. Its core usage is via the `codecov` command-line tool after installation. There is a separate `pycodecov` library for the Codecov API.

Quickstart

This quickstart demonstrates the typical workflow: first, generate an XML coverage report (e.g., with `pytest-cov`), then use the `codecov` command-line tool to upload the report to Codecov.io. The upload token (`CODECOV_TOKEN`) is usually required for private repositories and should be stored securely as an environment variable in your CI/CD pipeline. For public repositories, Codecov often auto-detects and uploads without an explicit token when run in supported CI environments.

# 1. Install necessary packages
pip install pytest pytest-cov

# 2. Run tests and generate coverage report (e.g., using pytest-cov)
pytest --cov=. --cov-report=xml

# 3. Upload coverage report to Codecov (usually in a CI environment)
# Replace CODECOV_TOKEN with your actual Codecov upload token for private repos
# For public repos, this is often not needed with CI integrations.
# Set CODECOV_TOKEN as an environment variable in your CI setup.
codecov -t "${CODECOV_TOKEN:-}"

view raw JSON →