CodeCarbon Documentation

The carbonboard local dashboard provides several visualization capabilities for analyzing CSV emissions logs:

• Summary and Equivalents: View net power consumption and emissions across projects, with real-world comparisons (e.g., weekly share of an average American household, miles driven, or LCD TV time).
• Regional Comparisons: Benchmark emissions against electricity grids across different countries to understand regional carbon intensity variations.
• Cloud Regions: Benchmark equivalent emissions across different cloud provider regions to identify the most eco-friendly hosting locations.

The online dashboard provides high-level and granular views of emissions data:

• Organization & Project Overview: Displays global energy consumption and emissions at the organization level, broken down by project, including real-world comparison points.
• Experiments, Runs & Detailed Metrics: Projects are organized into experiments, which contain multiple runs. Visualizations include bar charts for total emissions per experiment and bubble charts for individual runs.
• Run Drill-Down: Clicking a run bubble reveals full time-series graphs and detailed metadata, including timestamps, energy breakdowns, and hardware information.
• Global Carbon Intensity: Visualizes the regional carbon intensity of electricity production by country to assist in deployment region selection.

CodeCarbon is a mono-repo consisting of four main components:

1. codecarbon/: The core Python package used for tracking carbon emissions via CLI or library calls.
2. carbonserver/: A FastAPI-based REST API with PostgreSQL integration for data persistence and user management.
3. dashboard/viz: A Python-based interactive dashboard using Dash and Plotly that visualizes emission data from CSV files.
4. webapp/: A modern React/Next.js web application that connects to the carbonserver API.

Core logic and tests are located in tests/, usage examples in examples/, and deployment configurations in deploy/.

For iterative experiments, such as training multiple models in a loop or running long-lived Jupyter notebooks, use the explicit object pattern with EmissionsTracker. This provides fine-grained control over when tracking starts and stops.

Best Practice: Always wrap your training code in a try...finally block. Calling tracker.stop() inside the finally block ensures that CodeCarbon's internal scheduler is properly shut down and background threads are terminated, even if your training code encounters an error.

tracker = EmissionsTracker(project_name="my_experiment")
tracker.start()
try:
    # Your training code here
    pass
finally:
    emissions = tracker.stop()

Decide which tool to use based on where your code is executing:

• Use CodeCarbon when you run code on hardware you control. This includes training models, local inference, or any code running on your own machine, a local server, or a cloud Virtual Machine (VM).
• Use EcoLogits when you are calling remote GenAI APIs (such as OpenAI, Anthropic, Mistral, etc.) and want to estimate the environmental impact of those specific requests.

Both tools are complementary: CodeCarbon tracks local computing, while EcoLogits tracks remote API inference.

CodeCarbon estimates the electricity power consumption of your hardware (specifically CPU, GPU, and RAM) and applies the carbon intensity of the region where the computation is occurring.

Note that it does not explicitly model disk I/O, network transfers, displays, or cooling, as these are typically much smaller for local code-level experiments and are not easily exposed through low-overhead measurement interfaces.

CodeCarbon focuses on the direct emissions produced by running your code. It uses different data sources for energy carbon intensity depending on your infrastructure:

Cloud Computing

• Google Cloud: Uses Google's published carbon intensity data.
• AWS: Amazon does not make datacenter carbon footprints publicly available.
• Azure: Microsoft provides a Sustainability Calculator but does not publish specific datacenter carbon intensity.

Private Infrastructure

• Our World in Data: Used when available via ourworldindata.org.
• Global Petrol Prices: Uses the electricity mix from globalpetrolprices.com multiplied by the carbon intensity of the electricity source.
• Default: If no specific data is available, CodeCarbon defaults to 475 gCO2.eq/kWh (based on IEA data).

CodeCarbon parameters can be set using several methods. The priority order for these methods is defined in the Configuration guide. You can provide parameters via:

• Initializing EmissionsTracker() or OfflineEmissionsTracker()
• Using the @track_emissions decorator
• Providing a configuration file
• Setting environment variables

Key Concepts:

• PUE (Power Usage Effectiveness): A user-provided multiplication factor. Values typically range from 1.1 (green datacenters) to 2.2 (older datacenters).
• GPU Selection: If you use CUDA_VISIBLE_DEVICES or ROCR_VISIBLE_DEVICES to restrict GPU access, CodeCarbon will automatically populate gpu_ids. However, providing a manual gpu_ids value will override this automatic detection.