Configure CodeCarbon¶

Configuration priority¶

CodeCarbon is structured so that you can configure it in a hierarchical manner:

global parameters in your home folder ~/.codecarbon.config
local parameters (with respect to the current working directory) in ./.codecarbon.config
environment variables parameters starting with CODECARBON_
script parameters in the tracker's initialization as EmissionsTracker(param=value)

Configuration files

Configuration files must be named .codecarbon.config and start with a section header [codecarbon] as the first line in the file.

For instance:

~/.codecarbon.config

[codecarbon]
measure_power_secs=10
save_to_file=local-overwrite
emissions_endpoint=localhost:7777

./.codecarbon.config will override ~/.codecarbon.config if the same parameter is set in both files:

[codecarbon]
save_to_file = true
output_dir = /Users/victor/emissions
electricitymaps_api_token=script-overwrite
experiment_id = 235b1da5-aaaa-aaaa-aaaa-893681599d2c
log_level = DEBUG
tracking_mode = process

environment variables will override ./.codecarbon.config if the same parameter is set in both files:
```
export CODECARBON_GPU_IDS="0, 1"
export CODECARBON_LOG_LEVEL="WARNING"
```

script parameters will override environment variables if the same parameter is set in both:

EmissionsTracker(
   api_call_interval=4,
   save_to_api=True,
   electricitymaps_api_token="some-token")

Yields attributes:

{
    "measure_power_secs": 10,  # from ~/.codecarbon.config
    "save_to_file": True,   # from ./.codecarbon.config (override ~/.codecarbon.config)
    "api_call_interval": 4, # from script
    "save_to_api": True,   # from script
    "experiment_id": "235b1da5-aaaa-aaaa-aaaa-893681599d2c", # from ./.codecarbon.config
    "log_level": "WARNING", # from environment variable (override ./.codecarbon.config)
    "tracking_mode": "process", # from ./.codecarbon.config
    "emissions_endpoint": "localhost:7777", # from ~/.codecarbon.config
    "output_dir": "/Users/victor/emissions", # from ./.codecarbon.config
    "electricitymaps_api_token": "some-token", # from script (override ./.codecarbon.config)
    "gpu_ids": [0, 1], # from environment variable
}

Note

If you're wondering about the configuration files' syntax, be aware that under the hood codecarbon uses ConfigParser which relies on the INI syntax.

Electricity Maps API Token¶

By default, CodeCarbon estimates carbon intensity using annual country-level averages from Our World in Data. Providing an electricitymaps_api_token upgrades this to real-time carbon intensity data from the Electricity Maps API, giving more accurate emissions figures — especially useful if your grid's energy mix varies throughout the day.

Without a token: CodeCarbon uses a static annual average for your country.

With a token: CodeCarbon queries the Electricity Maps API for the current carbon intensity of your grid. The query runs at the end of each tracking run, and also periodically during long runs (every api_call_interval × measure_power_secs seconds; default: every ~2 minutes).

The Electricity Maps API offers a free tier. You can sign up and get a token at electricitymaps.com.

Set it in your config file:

[codecarbon]
electricitymaps_api_token = your-token-here

Or in code:

EmissionsTracker(electricitymaps_api_token="your-token-here")

Deprecated parameter

The old parameter name co2_signal_api_token still works for backward compatibility but is deprecated and will be removed in a future version. Use electricitymaps_api_token instead.

Tracking Mode¶

The tracking_mode parameter controls how CodeCarbon measures power consumption. It accepts two values:

"machine" (default): Measures power for the entire machine — total RAM in use and total CPU load across all processes.
"process": Isolates measurements to the tracked process — only the process's RAM usage and its share of CPU time are used to estimate power.

This setting affects RAM and CPU measurements. GPU power is always measured at the device level regardless of tracking mode.

Set it in your config file:

[codecarbon]
tracking_mode = process

Or in code:

EmissionsTracker(tracking_mode="process")

Note

"process" mode gives a lower-bound estimate of your code's footprint. "machine" mode is more conservative and accounts for all activity on the system.

Including DRAM in the CPU Measurement¶

When CodeCarbon reads the CPU energy counters, the hardware also exposes a DRAM domain measuring the memory controller. It is excluded by default, so that memory power is reported by the RAM tracker only and is not counted twice.

Set rapl_include_dram to add it to the CPU measurement:

[codecarbon]
rapl_include_dram = true

Or in code:

EmissionsTracker(rapl_include_dram=True)

Despite its name, this option applies to every counter-based CPU interface:

Linux: the dram domains of the RAPL powercap interface.
Windows 11: the DRAM channels of the Energy Meter Interface, which exposes the very same RAPL counters.

It has no effect when CodeCarbon falls back to TDP/CPU-load estimation, since that mode models the CPU package only.

Access internet through proxy server¶

If you need a proxy to access internet, which is needed to call a Web API, like Codecarbon API, you have to set environment variable HTTPS_PROXY, or HTTP_PROXY if calling an http:// endpoint.

You could do it in your shell:

export HTTPS_PROXY="http://0.0.0.0:0000"

Or in your Python code:

import os

os.environ["HTTPS_PROXY"] = "http://0.0.0.0:0000"

For more information, please read the requests library proxy documentation