Install & Compatibility
Where this runs
tested against v2.1.13 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
codecov
✓ codecov -t $CODECOV_TOKEN
✗ import codecov # for core uploading functionality
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.
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:-}"
codecov --version
Debug
Known issues
breakingThe `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.fixMigrate to the Codecov CLI (downloadable binary) or integrate the `codecov/codecov-action` for GitHub Actions. Refer to the official Codecov documentation for migration guides.
affects: All versions, including 2.1.13 and earlier.
breakingIn 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.fixWhile 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.
affects: <=2.1.12 (prior to its re-instatement as 2.1.13)
gotchaUsers 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.fixConsider 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.
affects: All versions.
gotchaIncorrect 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.fixAlways 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.
affects: All versions.
Upgrade
Version history
2.1.13latest on PyPI · released Apr 17, 2023
Audit
Dependencies
requestsrequiredRequired for making HTTP requests to the Codecov API.
coveragerequiredCommonly used for generating coverage reports that Codecov uploads. The `codecov` package itself also depends on it.
pytest-covoptionalA pytest plugin for measuring coverage, frequently used to generate reports consumed by Codecov.