codecarbon

library3.2.8pypypi✓ verified 86d ago

CodeCarbon is an open-source Python library that helps estimate and track the CO2 emissions produced by computing, particularly for machine learning models. It measures energy consumption of CPU, GPU, and RAM, and combines it with regional carbon intensity data to provide CO2 equivalent emissions. Currently at version 3.2.6, it maintains an active development and release cadence, offering both Python API and CLI for monitoring and reporting.

ai-ml observability devops

pip install codecarbon

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CODECARBON

codecarbon

ai-mlpythonv3.2.8

Install

15.0s avg

Import

1977ms

Disk

260MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.8 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 2.038s · 265.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 15.0s · import 1.916s · 253MB

260MB installed

● package 260MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EmissionsTracker

✓ from codecarbon import EmissionsTracker

track_emissions

✓ from codecarbon import track_emissions

✗ import codecarbon; codecarbon.track_emissions

The `track_emissions` function is typically used as a decorator and is directly imported from the `codecarbon` package.

OfflineEmissionsTracker

✓ from codecarbon import OfflineEmissionsTracker

This quickstart demonstrates how to use the `EmissionsTracker` class to measure the carbon footprint of a Python code block. It initializes a tracker, starts it before the task, stops it after, and prints the total emissions. A detailed report is saved to `emissions.csv` by default.

import time from codecarbon import EmissionsTracker def train_model(): # Simulate some computationally intensive task print("Starting model training...") time.sleep(10) # Your actual ML code here print("Model training finished.") if __name__ == "__main__": tracker = EmissionsTracker() tracker.start() train_model() emissions = tracker.stop() print(f"Emissions: {emissions} kg CO₂") print("Check emissions.csv for detailed report.")

codecarbon --version

Debug

Known issues

breakingVersion 3.2.4 was broken due to packaging issues and was subsequently yanked from PyPI. Direct upgrades to 3.2.4 might have failed or resulted in a broken installation.

fix

Ensure you are using `codecarbon==3.2.5` or later. If you installed 3.2.4, uninstall it and reinstall the latest version: `pip uninstall codecarbon && pip install codecarbon`.

affects: 3.2.4

breakingCodeCarbon has updated its underlying APIs for carbon intensity data (e.g., from CO2 Signal to Electricity Maps) and its authentication backend (from Fief to Keycloak). Users relying on specific API integrations or the CodeCarbon dashboard might need to update configurations or API keys.

fix

Review the official CodeCarbon documentation for changes to API endpoints, authentication, and configuration files (`.codecarbon.config`). Re-run `codecarbon login` if using the online dashboard.

affects: 3.1.1, 3.2.3

gotchaThe accuracy of hardware power consumption measurements (CPU, GPU) depends on the availability of specific underlying tools (e.g., Intel Power Gadget/RAPL, pynvml, amdsmi) on your operating system. Without these, CodeCarbon will fall back to less accurate estimation methods.

fix

For the most accurate tracking, consult the CodeCarbon documentation's methodology section to install the recommended power measurement tools for your specific hardware and OS.

affects: All

gotchaBy default, CodeCarbon's `EmissionsTracker` uses a lock file to prevent multiple instances from running concurrently in the same directory, which can cause an error if a previous run crashed or if you intentionally try to run multiple trackers.

fix

If you need to run multiple trackers, initialize `EmissionsTracker` with `allow_multiple_runs=True`. If an error occurs due to a stale lock file, manually delete `/tmp/.codecarbon.lock` (or equivalent on your OS) or restart your environment.

affects: All

gotchaCodeCarbon measures emissions from local computing (your hardware). It does not track emissions from remote GenAI API calls (e.g., OpenAI, Anthropic, Mistral). For those, CodeCarbon recommends using EcoLogits.

fix

For tracking remote GenAI API call emissions, consider using complementary tools like EcoLogits. CodeCarbon is intended for monitoring code running on your local machine or managed compute infrastructure.

affects: All

Errors

Common errors & fixes

Another instance of codecarbon is probably running as we find /tmp/.codecarbon.lock. Turn off the other instance to be able to run this one or use allow_multiple_runs or delete the file. Exiting.

An `EmissionsTracker` instance detected a lock file, indicating another tracker is active or a previous run terminated abnormally.

fix

If you intended to run multiple trackers, initialize with `EmissionsTracker(allow_multiple_runs=True)`. Otherwise, ensure no other `codecarbon` process is running or manually delete the lock file (e.g., `/tmp/.codecarbon.lock` on Linux).

ApiClient Error when calling the API on https://api.codecarbon.io/... API return http code 500 and answer : {"detail":"Generic error"}

Failed communication with the CodeCarbon online API, often due to misconfigured API keys, project IDs, or network issues.

fix

Verify your internet connection. Check the `api_endpoint`, `api_key`, `organization_id`, `project_id`, and `experiment_id` in your global `~/.codecarbon.config` or local `.codecarbon.config` file. Re-run `codecarbon login` or `codecarbon config` CLI commands to re-authenticate and configure.

AttributeError: module 'codecarbon' has no attribute 'EmissionsTracker'

The `EmissionsTracker` class was not found when attempting to import, likely due to a partial installation, a corrupted environment, or incorrect import statement.

fix

Ensure `codecarbon` is correctly installed: `pip install --upgrade codecarbon`. Verify the import statement: `from codecarbon import EmissionsTracker`. If running in an IDE, restart the Python kernel or environment.

FileNotFoundError: [Errno 2] No such file or directory: 'emissions.csv'

Attempting to read `emissions.csv` before `EmissionsTracker.stop()` has been called, or the file was saved to a different location.

fix

Ensure `tracker.stop()` is called before trying to access `emissions.csv`. The file is saved in the directory where the script is run by default, or to a path specified by the `save_to_file` parameter in `EmissionsTracker`.

Upgrade

Version history

3.2.8latest on PyPI · released Jun 7, 2026

Audit

Dependencies

pythonrequiredMinimum Python version required for the library.

pynvmloptionalRequired for accurate NVIDIA GPU power consumption tracking. CodeCarbon falls back to estimation without it.

intel-power-gadgetoptionalOptional, but recommended for accurate Intel CPU power consumption tracking on supported systems (Linux/Windows). CodeCarbon falls back to estimation without it.

intel-raploptionalOptional, but recommended for accurate Intel CPU power consumption tracking on supported systems (Linux). CodeCarbon falls back to estimation without it.

amdsmioptionalRequired for AMD ROCm support for GPU power tracking (introduced in v3.2.4).

carbonboardoptionalCLI tool and dashboard for local visualization of CodeCarbon's `emissions.csv` output.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mlco2/codecarbon ↗

packagehttps://pypi.org/project/codecarbon/ ↗

homepagehttps://codecarbon.io/ ↗

docshttps://docs.codecarbon.io/ ↗

changeloghttps://github.com/mlco2/codecarbon/releases ↗