Carbon dioxide (CO₂) emissions, expressed as kilograms of CO₂-equivalents [CO₂eq], are the product of two main factors :

C = Carbon Intensity of the electricity consumed for computation: quantified as g of CO₂ emitted per kilowatt-hour of electricity.

E = Energy Consumed by the computational infrastructure: quantified as kilowatt-hours.

Carbon dioxide emissions (CO₂eq) can then be calculated as C * E

Carbon Intensity

Carbon Intensity of the consumed electricity is calculated as a weighted average of the emissions from the different energy sources that are used to generate electricity, including fossil fuels and renewables. In this toolkit, the fossil fuels coal, petroleum, and natural gas are associated with specific carbon intensities: a known amount of carbon dioxide is emitted for each kilowatt-hour of electricity generated. Renewable or low-carbon fuels include solar power, hydroelectricity, biomass, geothermal, and more. The nearby energy grid contains a mixture of fossil fuels and low-carbon energy sources, called the Energy Mix. Based on the mix of energy sources in the local grid, this package calculates the Carbon Intensity of the electricity consumed.

Grid Energy Mix

When available, CodeCarbon uses global carbon intensity of electricity per cloud provider ( here ) or per country ( here ).

If we don’t have the global carbon intensity or electricity of a country, but we have its electricity mix, we compute the carbon intensity of electricity using this table:

Carbon Intensity Across Energy Sources

Energy Source

Carbon Intensity (kg/MWh)





Natural Gas













Then, for example, if the Energy Mix of the Grid Electricity is 25% Coal, 35% Petroleum, 26% Natural Gas and 14% Nuclear:

Net Carbon Intensity = 0.25 * 995 + 0.35 * 816 + 0.26 * 743 + 0.14 * 29 = 731.59 kgCO₂/kWh

If ever we have neither the global carbon intensity of a country nor it’s electricity mix, we apply a world avarage of 475 gCO2.eq/KWh ( source ).

As you can see, we try to be as accurate as possible in estimating carbon intensity of electricity. Still there is room for improvement and all contributions are welcome.

Power Usage

Power supply to the underlying hardware is tracked at frequent time intervals. This is a configurable parameter measure_power_secs, with default value 15 seconds, that can be passed when instantiating the emissions tracker.

Currently, the package supports the following hardware infrastructure.


Tracks Nvidia GPUs energy consumption using pynvml library (installed with the package).


CodeCarbon uses a 3 Watts for 8 BG ratio source . This mesure is not satisfying and if ever you have an idea how to enhance it please do not hesitate to contribute.


  • On Windows or Mac

Tracks Intel processors energy consumption using the Intel Power Gadget. You need to install it yourself from this source .

  • On Linux

Tracks Intel and AMD processor energy consumption from Intel RAPL files at \sys\class\powercap\intel-rapl ( reference ). All CPUs listed in this directory will be tracked. Help us improve this and make it configurable.

Note: The Power Consumption will be tracked only if the RAPL files exist at the above mentioned path

If none of the tracking tools are available on a computing resource, CodeCarbon will be switched to a fall back mode:
  • It will first detect which CPU hardware is currently in use, and then map it to a data source listing 2000+ Intel and AMD CPUs and their corresponding thermal design powers (TDPs).

  • If the CPU is not found in the data source, a global constant will be applied. CodeCarbon assumes that 50% of the TDP will be the average power consumption to make this approximation.

  • We could not find any good resource showing statistical relationships between TDP and average power so we empirically tested that 50% is a decent approximation.

The net Energy Used is the net power supply consumed during the compute time, measured as kWh.

Energy = Power * Time


Energy Usage Reports: Environmental awareness as part of algorithmic accountability

How CodeCarbon Works

CodeCarbon use a scheduler that, by default, call for the measure every 15 seconds so it has no significant overhead.

The measure itself is fast and CodeCarbon is designed to be as light as possible with a small memory footprint.

The scheduler is started when the first start method is called and stopped when stop method is called.