{"id":3929,"library":"codecov","title":"Codecov Python Uploader","description":"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.","status":"deprecated","version":"2.1.13","language":"en","source_language":"en","source_url":"https://github.com/codecov/codecov-python","tags":["code coverage","testing","CI/CD","developer tools","metrics","deprecated"],"install":[{"cmd":"pip install codecov","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Required for making HTTP requests to the Codecov API.","package":"requests","optional":false},{"reason":"Commonly used for generating coverage reports that Codecov uploads. The `codecov` package itself also depends on it.","package":"coverage","optional":false},{"reason":"A pytest plugin for measuring coverage, frequently used to generate reports consumed by Codecov.","package":"pytest-cov","optional":true}],"imports":[{"note":"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.","wrong":"import codecov # for core uploading functionality","symbol":"codecov","correct":"codecov -t $CODECOV_TOKEN"}],"quickstart":{"code":"# 1. Install necessary packages\npip install pytest pytest-cov\n\n# 2. Run tests and generate coverage report (e.g., using pytest-cov)\npytest --cov=. --cov-report=xml\n\n# 3. Upload coverage report to Codecov (usually in a CI environment)\n# Replace CODECOV_TOKEN with your actual Codecov upload token for private repos\n# For public repos, this is often not needed with CI integrations.\n# Set CODECOV_TOKEN as an environment variable in your CI setup.\ncodecov -t \"${CODECOV_TOKEN:-}\"","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, including 2.1.13 and earlier."},{"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.","message":"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.","severity":"breaking","affected_versions":"<=2.1.12 (prior to its re-instatement as 2.1.13)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}