Track & reduce CO₂ emissions from your local computing
Estimate and track carbon emissions from your computer, quantify and analyze their impact.
- A lightweight, easy to use Python library – Simple API to track emissions
- Open source, free & community driven – Built by and for the community
- Effective visual outputs – Put emissions in context with real-world equivalents
Tracking GenAI API calls? CodeCarbon measures emissions from local computing (your hardware). To track emissions from remote GenAI API calls (OpenAI, Anthropic, Mistral, etc.), use EcoLogits. Both tools are complementary.
Join the community! Have questions, want to share your work, or contribute? Join us on Discord – we're here to help and excited to hear from you!
Installation
pip install codecarbon
If you use Conda:
conda activate your_env
pip install codecarbon
More installation options: installation docs.
Quickstart (Python)
from codecarbon import EmissionsTracker
tracker = EmissionsTracker()
tracker.start()
# Your code here
emissions = tracker.stop()
print(f"Emissions: {emissions} kg CO₂")
Quickstart (CLI)
Track a command without changing your code:
codecarbon monitor --no-api -- python train.py
Detect your hardware:
codecarbon detect
Full CLI guide: CLI tutorial.
Configuration
You can configure CodeCarbon using:
~/.codecarbon.config(global)./.codecarbon.config(project-local)CODECARBON_*environment variables- Python arguments (
EmissionsTracker(...))
Configuration precedence and examples: configuration guide.
How it works
We created a Python package that estimates your hardware electricity power consumption (GPU + CPU + RAM) and we apply to it the carbon intensity of the region where the computing is done.
CodeCarbon focuses on the main compute components it can measure or estimate directly: CPU, GPU, and RAM. It does not separately model disk I/O, network transfers, displays, cooling, or other peripherals because those sources are usually much smaller for local code-level experiments and are not exposed through the same low-overhead measurement interfaces.
We explain more about this calculation in the Methodology section of the documentation.
Visualize
You can visualize your experiment emissions on the dashboard or locally with carbonboard.
Quick links
| Section | Description |
|---|---|
| Quickstart | Get started in 5 minutes |
| Installation | Install CodeCarbon |
| CLI Tutorial | Track emissions from the command line |
| Python API Tutorial | Track emissions in Python code |
| Comparing Model Efficiency | Measure carbon efficiency across ML models |
| API Reference | Full parameter documentation |
| Framework examples (scikit-learn) | Task-oriented ML framework examples |
| Methodology | How emissions are calculated |
| When to use CodeCarbon vs EcoLogits | Choose the right tool |
| EcoLogits | Track emissions from GenAI API calls |
| Discord Community | Chat with us and the community |
Links
- Main website to learn why we do this.
- Dashboard to see your emissions.
- Documentation to learn how to use the package and our methodology.
- EcoLogits to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
- mlco2 on GitHub for our other open-source projects.
- GitHub to look at the source code and contribute.
- Discord to chat with us.
Contributing
We are hoping that the open-source community will help us edit the code and make it better!
You are welcome to open issues, even suggest solutions and better still contribute the fix/improvement! We can guide you if you're not sure where to start but want to help us out.
Check out our contribution guidelines.
Feel free to chat with us on Discord.
Citation
If you find CodeCarbon useful for your research, you can find a citation under a variety of formats on Zenodo.
BibTeX
@software{benoit_courty_2024_11171501,
author = {Benoit Courty and
Victor Schmidt and
Sasha Luccioni and
Goyal-Kamal and
MarionCoutarel and
Boris Feld and
Jérémy Lecourt and
LiamConnell and
Amine Saboni and
Inimaz and
supatomic and
Mathilde Léval and
Luis Blanche and
Alexis Cruveiller and
ouminasara and
Franklin Zhao and
Aditya Joshi and
Alexis Bogroff and
Hugues de Lavoreille and
Niko Laskaris and
Edoardo Abati and
Douglas Blank and
Ziyao Wang and
Armin Catovic and
Marc Alencon and
Michał Stęchły and
Christian Bauer and
Lucas Otávio N. de Araújo and
JPW and
MinervaBooks},
title = {mlco2/codecarbon: v2.4.1},
month = may,
year = {2024},
publisher = {Zenodo},
version = {v2.4.1},
doi = {10.5281/zenodo.11171501},
url = {https://doi.org/10.5281/zenodo.11171501}
}
Contact
Feel free to chat with us on Discord.
Codecarbon was formerly developed by volunteers from Mila and the DataForGoodFR community alongside donated professional time of engineers at Comet.ml and BCG GAMMA.
Now CodeCarbon is supported by Code Carbon, a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
Sponsors
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file codecarbon-3.3.0.tar.gz.
File metadata
- Download URL: codecarbon-3.3.0.tar.gz
- Upload date:
- Size: 447.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
80dad7db6e62f5c6b716afd3746ea892146d36071ca1e786683899c6de75d6f7
|
|
| MD5 |
8b88f3b41058bb472f8e5bfc2217145e
|
|
| BLAKE2b-256 |
f4330954d862a3ba83ca6f6c6103b75b3467eef6013e86af3e51fa9c0507f7d5
|
Provenance
The following attestation bundles were made for codecarbon-3.3.0.tar.gz:
Publisher:
python-publish.yml on mlco2/codecarbon
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codecarbon-3.3.0.tar.gz -
Subject digest:
80dad7db6e62f5c6b716afd3746ea892146d36071ca1e786683899c6de75d6f7 - Sigstore transparency entry: 2340470881
- Sigstore integration time:
-
Permalink:
mlco2/codecarbon@4dde6e30f061f9fa718fa0396b284b3c965a5aad -
Branch / Tag:
refs/tags/3.3.0 - Owner: https://github.com/mlco2
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@4dde6e30f061f9fa718fa0396b284b3c965a5aad -
Trigger Event:
release
-
Statement type:
File details
Details for the file codecarbon-3.3.0-py3-none-any.whl.
File metadata
- Download URL: codecarbon-3.3.0-py3-none-any.whl
- Upload date:
- Size: 396.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
38cbe0b4fcc7e6ebde529c49fb4cd05ef29f3da3ec43c81acdd2f0acda4f195e
|
|
| MD5 |
0ac9083e9acbe7f24f3fe90b70fa4829
|
|
| BLAKE2b-256 |
8f76619b837c3ed1cee46235bdae3a6959ca9fc90c2f0b5cb115036e91d70574
|
Provenance
The following attestation bundles were made for codecarbon-3.3.0-py3-none-any.whl:
Publisher:
python-publish.yml on mlco2/codecarbon
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codecarbon-3.3.0-py3-none-any.whl -
Subject digest:
38cbe0b4fcc7e6ebde529c49fb4cd05ef29f3da3ec43c81acdd2f0acda4f195e - Sigstore transparency entry: 2340470887
- Sigstore integration time:
-
Permalink:
mlco2/codecarbon@4dde6e30f061f9fa718fa0396b284b3c965a5aad -
Branch / Tag:
refs/tags/3.3.0 - Owner: https://github.com/mlco2
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@4dde6e30f061f9fa718fa0396b284b3c965a5aad -
Trigger Event:
release
-
Statement type:
