codecarbon


Namecodecarbon JSON
Version 3.0.4 PyPI version JSON
download
home_pageNone
SummaryNone
upload_time2025-07-15 09:13:27
maintainerNone
docs_urlNone
authorMila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
requires_python>=3.7
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ![banner](docs/edit/images/banner.png)

Estimate and track carbon emissions from your computer, quantify and analyze their impact.

[**Documentation**](https://mlco2.github.io/codecarbon)

<br/>

[![](https://anaconda.org/conda-forge/codecarbon/badges/version.svg)](https://anaconda.org/conda-forge/codecarbon)
[![](https://anaconda.org/codecarbon/codecarbon/badges/version.svg)](https://anaconda.org/codecarbon/codecarbon)
[![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/)
[![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731)
[![Downloads](https://static.pepy.tech/badge/codecarbon/month)](https://pepy.tech/project/codecarbon)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon)


- [About CodeCarbon ๐Ÿ’ก](#about-codecarbon-)
- [Quickstart ๐Ÿš€](#quickstart-)
    - [Installation ๐Ÿ”ง](#installation-)
    - [Start to estimate your impact ๐Ÿ“](#start-to-estimate-your-impact-)
      - [Monitoring your whole machine](#monitoring-your-machine-)
      - [In your python code](#in-your-python-code-)
      - [Visualize](#visualize-)
- [Contributing ๐Ÿค](#contributing-)
- [How To Cite ๐Ÿ“](#how-to-cite-)
- [Contact ๐Ÿ“](#contact-)

# About CodeCarbon ๐Ÿ’ก

**CodeCarbon** started with a quite simple question:

**What is the carbon emission impact of my computer program? :shrug:**

We found some global data like "computing currently represents roughly 0.5% of the worldโ€™s energy consumption" but nothing on our individual/organisation level impact.

At **CodeCarbon**, we believe, along with Niels Bohr, that "Nothing exists until it is measured". So we found a way to estimate how much CO<sub>2</sub> we produce while running our code.

*How?*

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.

![calculation Summary](docs/edit/images/calculation.png)

We explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.

Our hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.

**So ready to "change the world one run at a time"? Let's start with a very quick set up.**

# Quickstart ๐Ÿš€

## Installation ๐Ÿ”ง

**From PyPI repository**
```python
pip install codecarbon
```

**From Conda repository**
```python
conda install -c codecarbon codecarbon
```
To see more installation options please refer to the documentation: [**Installation**](https://mlco2.github.io/codecarbon/installation.html#)

## Start to estimate your impact ๐Ÿ“

### Without using the online dashboard

```python
from codecarbon import track_emissions
@track_emissions()
def your_function_to_track():
  # your code
```

After running your code, you will find an `emissions.csv` that you can visualize with `carbonboard --filepath="examples/emissions.csv"`.

### With the online dashboard

To use the online dashboard you need to create an account on [**CodeCarbon Dashboard**](https://dashboard.codecarbon.io/).
Once you have an account, you can create an experiment_id to track your emissions.

To get an experiment_id enter:
```python
! codecarbon login
```
You can now store it in a **.codecarbon.config** at the root of your project
```python
[codecarbon]
log_level = DEBUG
save_to_api = True
experiment_id = 2bcbcbb8-850d-4692-af0d-76f6f36d79b2 #the experiment_id you get with init
```
Now you have 2 main options:

### Monitoring your machine ๐Ÿ’ป

In your command prompt use:
```codecarbon monitor```
The package will track your emissions independently from your code.

### In your Python code ๐Ÿ
```python
from codecarbon import track_emissions
@track_emissions()
def your_function_to_track():
  # your code
  ```
The package will track the emissions generated by the execution of your function.

There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://mlco2.github.io/codecarbon/usage.html#)

## Visualize ๐Ÿ“Š

You can now visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/).
![dashboard](docs/edit/images/dashboard.png)


> Hope you enjoy your first steps monitoring your carbon computing impact!
> Thanks to the incredible codecarbon community ๐Ÿ’ช๐Ÿผ a lot more options are available using *codecarbon* including:
> - offline mode
> - cloud mode
> - comet integration...
>
> Please explore the [**Documentation**](https://mlco2.github.io/codecarbon) to learn about it
> If ever what your are looking for is not yet implemented, let us know through the *issues* and even better become one of our ๐Ÿฆธ๐Ÿผโ€โ™€๏ธ๐Ÿฆธ๐Ÿผโ€โ™‚๏ธ contributors! more info ๐Ÿ‘‡๐Ÿผ


# 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 ๐Ÿฅ‡

In order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.

Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)

Contact [@vict0rsch](https://github.com/vict0rsch) to be added to our slack workspace if you want to contribute regularly!

# How To Cite ๐Ÿ“

If you find CodeCarbon useful for your research, you can find a citation under a variety of formats on [Zenodo](https://zenodo.org/records/11171501).

Here is a sample for BibTeX:
```tex
@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 ๐Ÿ“

Maintainers are [@vict0rsch](https://github.com/vict0rsch) [@benoit-cty](https://github.com/benoit-cty) and [@SaboniAmine](https://github.com/saboniamine). Codecarbon is developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).

## Star History

Comparison of the number of stars accumulated by the different Python CO2 emissions projects:
[![Star History Chart](https://api.star-history.com/svg?repos=mlco2/codecarbon,lfwa/carbontracker,sb-ai-lab/Eco2AI,fvaleye/tracarbon,Breakend/experiment-impact-tracker&type=Date)](https://star-history.com/#mlco2/codecarbon&lfwa/carbontracker&sb-ai-lab/Eco2AI&fvaleye/tracarbon&Breakend/experiment-impact-tracker&Date)


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "codecarbon",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": null,
    "author": "Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/10/1e/cab62e273ab8bfb6f7b8467b5ec4d2955ca98d9fa437b3b12e5e68ced94e/codecarbon-3.0.4.tar.gz",
    "platform": null,
    "description": "![banner](docs/edit/images/banner.png)\n\nEstimate and track carbon emissions from your computer, quantify and analyze their impact.\n\n[**Documentation**](https://mlco2.github.io/codecarbon)\n\n<br/>\n\n[![](https://anaconda.org/conda-forge/codecarbon/badges/version.svg)](https://anaconda.org/conda-forge/codecarbon)\n[![](https://anaconda.org/codecarbon/codecarbon/badges/version.svg)](https://anaconda.org/codecarbon/codecarbon)\n[![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/)\n[![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731)\n[![Downloads](https://static.pepy.tech/badge/codecarbon/month)](https://pepy.tech/project/codecarbon)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon)\n\n\n- [About CodeCarbon \ud83d\udca1](#about-codecarbon-)\n- [Quickstart \ud83d\ude80](#quickstart-)\n    - [Installation \ud83d\udd27](#installation-)\n    - [Start to estimate your impact \ud83d\udccf](#start-to-estimate-your-impact-)\n      - [Monitoring your whole machine](#monitoring-your-machine-)\n      - [In your python code](#in-your-python-code-)\n      - [Visualize](#visualize-)\n- [Contributing \ud83e\udd1d](#contributing-)\n- [How To Cite \ud83d\udcdd](#how-to-cite-)\n- [Contact \ud83d\udcdd](#contact-)\n\n# About CodeCarbon \ud83d\udca1\n\n**CodeCarbon** started with a quite simple question:\n\n**What is the carbon emission impact of my computer program? :shrug:**\n\nWe found some global data like \"computing currently represents roughly 0.5% of the world\u2019s energy consumption\" but nothing on our individual/organisation level impact.\n\nAt **CodeCarbon**, we believe, along with Niels Bohr, that \"Nothing exists until it is measured\". So we found a way to estimate how much CO<sub>2</sub> we produce while running our code.\n\n*How?*\n\nWe 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.\n\n![calculation Summary](docs/edit/images/calculation.png)\n\nWe explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.\n\nOur hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.\n\n**So ready to \"change the world one run at a time\"? Let's start with a very quick set up.**\n\n# Quickstart \ud83d\ude80\n\n## Installation \ud83d\udd27\n\n**From PyPI repository**\n```python\npip install codecarbon\n```\n\n**From Conda repository**\n```python\nconda install -c codecarbon codecarbon\n```\nTo see more installation options please refer to the documentation: [**Installation**](https://mlco2.github.io/codecarbon/installation.html#)\n\n## Start to estimate your impact \ud83d\udccf\n\n### Without using the online dashboard\n\n```python\nfrom codecarbon import track_emissions\n@track_emissions()\ndef your_function_to_track():\n  # your code\n```\n\nAfter running your code, you will find an `emissions.csv` that you can visualize with `carbonboard --filepath=\"examples/emissions.csv\"`.\n\n### With the online dashboard\n\nTo use the online dashboard you need to create an account on [**CodeCarbon Dashboard**](https://dashboard.codecarbon.io/).\nOnce you have an account, you can create an experiment_id to track your emissions.\n\nTo get an experiment_id enter:\n```python\n! codecarbon login\n```\nYou can now store it in a **.codecarbon.config** at the root of your project\n```python\n[codecarbon]\nlog_level = DEBUG\nsave_to_api = True\nexperiment_id = 2bcbcbb8-850d-4692-af0d-76f6f36d79b2 #the experiment_id you get with init\n```\nNow you have 2 main options:\n\n### Monitoring your machine \ud83d\udcbb\n\nIn your command prompt use:\n```codecarbon monitor```\nThe package will track your emissions independently from your code.\n\n### In your Python code \ud83d\udc0d\n```python\nfrom codecarbon import track_emissions\n@track_emissions()\ndef your_function_to_track():\n  # your code\n  ```\nThe package will track the emissions generated by the execution of your function.\n\nThere is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://mlco2.github.io/codecarbon/usage.html#)\n\n## Visualize \ud83d\udcca\n\nYou can now visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/).\n![dashboard](docs/edit/images/dashboard.png)\n\n\n> Hope you enjoy your first steps monitoring your carbon computing impact!\n> Thanks to the incredible codecarbon community \ud83d\udcaa\ud83c\udffc a lot more options are available using *codecarbon* including:\n> - offline mode\n> - cloud mode\n> - comet integration...\n>\n> Please explore the [**Documentation**](https://mlco2.github.io/codecarbon) to learn about it\n> If ever what your are looking for is not yet implemented, let us know through the *issues* and even better become one of our \ud83e\uddb8\ud83c\udffc\u200d\u2640\ufe0f\ud83e\uddb8\ud83c\udffc\u200d\u2642\ufe0f contributors! more info \ud83d\udc47\ud83c\udffc\n\n\n# Contributing \ud83e\udd1d\n\nWe are hoping that the open-source community will help us edit the code and make it better!\n\nYou 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 \ud83e\udd47\n\nIn order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.\n\nCheck out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)\n\nContact [@vict0rsch](https://github.com/vict0rsch) to be added to our slack workspace if you want to contribute regularly!\n\n# How To Cite \ud83d\udcdd\n\nIf you find CodeCarbon useful for your research, you can find a citation under a variety of formats on [Zenodo](https://zenodo.org/records/11171501).\n\nHere is a sample for BibTeX:\n```tex\n@software{benoit_courty_2024_11171501,\n  author       = {Benoit Courty and\n                  Victor Schmidt and\n                  Sasha Luccioni and\n                  Goyal-Kamal and\n                  MarionCoutarel and\n                  Boris Feld and\n                  J\u00e9r\u00e9my Lecourt and\n                  LiamConnell and\n                  Amine Saboni and\n                  Inimaz and\n                  supatomic and\n                  Mathilde L\u00e9val and\n                  Luis Blanche and\n                  Alexis Cruveiller and\n                  ouminasara and\n                  Franklin Zhao and\n                  Aditya Joshi and\n                  Alexis Bogroff and\n                  Hugues de Lavoreille and\n                  Niko Laskaris and\n                  Edoardo Abati and\n                  Douglas Blank and\n                  Ziyao Wang and\n                  Armin Catovic and\n                  Marc Alencon and\n                  Micha\u0142\u00a0St\u0119ch\u0142y and\n                  Christian Bauer and\n                  Lucas Ot\u00e1vio N. de Ara\u00fajo and\n                  JPW and\n                  MinervaBooks},\n  title        = {mlco2/codecarbon: v2.4.1},\n  month        = may,\n  year         = 2024,\n  publisher    = {Zenodo},\n  version      = {v2.4.1},\n  doi          = {10.5281/zenodo.11171501},\n  url          = {https://doi.org/10.5281/zenodo.11171501}\n}\n```\n\n# Contact \ud83d\udcdd\n\nMaintainers are [@vict0rsch](https://github.com/vict0rsch) [@benoit-cty](https://github.com/benoit-cty) and [@SaboniAmine](https://github.com/saboniamine). Codecarbon is developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).\n\n## Star History\n\nComparison of the number of stars accumulated by the different Python CO2 emissions projects:\n[![Star History Chart](https://api.star-history.com/svg?repos=mlco2/codecarbon,lfwa/carbontracker,sb-ai-lab/Eco2AI,fvaleye/tracarbon,Breakend/experiment-impact-tracker&type=Date)](https://star-history.com/#mlco2/codecarbon&lfwa/carbontracker&sb-ai-lab/Eco2AI&fvaleye/tracarbon&Breakend/experiment-impact-tracker&Date)\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": null,
    "version": "3.0.4",
    "project_urls": {
        "Changelog": "https://github.com/mlco2/codecarbon/releases",
        "Dashboard": "http://dashboard.codecarbon.io/",
        "Documentation": "https://mlco2.github.io/codecarbon/",
        "Homepage": "https://codecarbon.io/",
        "Issues": "https://github.com/mlco2/codecarbon/issues",
        "Repository": "https://github.com/mlco2/codecarbon"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ccd6d5847cafa3b9a471e56ffe78b0a246b2384795ab4b75169a7032c4f0ae60",
                "md5": "2f45e56248617a71dde7736524c6a4ef",
                "sha256": "6f47dd6fa52fd25936b632bf22f85e7df0e8def683d68df55487e0f4e8bd688c"
            },
            "downloads": -1,
            "filename": "codecarbon-3.0.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2f45e56248617a71dde7736524c6a4ef",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 277676,
            "upload_time": "2025-07-15T09:13:25",
            "upload_time_iso_8601": "2025-07-15T09:13:25.627615Z",
            "url": "https://files.pythonhosted.org/packages/cc/d6/d5847cafa3b9a471e56ffe78b0a246b2384795ab4b75169a7032c4f0ae60/codecarbon-3.0.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "101ecab62e273ab8bfb6f7b8467b5ec4d2955ca98d9fa437b3b12e5e68ced94e",
                "md5": "ae61203277552d51b84a68cc01c25dec",
                "sha256": "4292fede09e44753b1185a8b91c53e1ed9108692733f612f32c44cab779dcc8c"
            },
            "downloads": -1,
            "filename": "codecarbon-3.0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "ae61203277552d51b84a68cc01c25dec",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 296194,
            "upload_time": "2025-07-15T09:13:27",
            "upload_time_iso_8601": "2025-07-15T09:13:27.353200Z",
            "url": "https://files.pythonhosted.org/packages/10/1e/cab62e273ab8bfb6f7b8467b5ec4d2955ca98d9fa437b3b12e5e68ced94e/codecarbon-3.0.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-15 09:13:27",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mlco2",
    "github_project": "codecarbon",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "codecarbon"
}
        
Elapsed time: 1.78731s