CodeCarbon

CodeCarbon monitors real-time power draw from the physical hardware executing the code, not just theoretical thermal design power (TDP).

• CPU Tracking: Queries Intel RAPL (Running Average Power Limit) interfaces on Linux and Intel Power Gadget on macOS/Windows for direct socket-level energy measurement.
• GPU Tracking: Integrates with NVIDIA Management Library (NVML) via pynvml to sample actual GPU power draw in watts during CUDA kernel execution.
• RAM Monitoring: Estimates memory power consumption as a linear function of allocated capacity, accounting for the baseline and dynamic power states of DRAM modules.
• Fallback Strategy: If hardware interfaces are unavailable, defaults to a conservative TDP-based estimation model using the processor's rated maximum power multiplied by a utilization coefficient.

CodeCarbon translates raw energy consumption (kWh) into carbon dioxide equivalent (CO2eq) by applying a regional carbon intensity factor specific to the geographic location of the compute infrastructure.

• Global Coverage: Maintains a public CSV dataset of carbon intensities for all countries and major cloud regions, sourced from the Carbon Intensity API and the Global Energy Monitor.
• Cloud Provider Detection: Automatically infers the compute region for major cloud providers (AWS, Azure, GCP) by parsing instance metadata endpoints, eliminating manual configuration.
• Private Infrastructure: For on-premise data centers, users can manually specify a country code or a custom carbon intensity value (gCO2eq/kWh) to override the automatic detection.
• Dynamic Updates: The emission factor dataset is versioned and can be updated independently of the library to reflect real-world grid decarbonization trends.

CodeCarbon is designed for minimal friction integration into existing Python data science and machine learning pipelines using a simple decorator pattern.

• @track_emissions Decorator: Wrapping a training function with this decorator automatically starts an emissions tracker before execution and stops it upon completion, logging the total footprint.
• Context Manager: The EmissionsTracker class can be used as a context manager (with EmissionsTracker() as tracker:) for fine-grained control over the measurement window within a script.
• Task-Level Granularity: Supports tracking multiple discrete tasks within a single process, allowing users to isolate the footprint of data preprocessing, training, and evaluation phases separately.
• Minimal Overhead: The power sampling loop runs in a background thread with a configurable interval (default 15 seconds), adding negligible computational overhead to the primary workload.

CodeCarbon generates structured, machine-readable output artifacts that feed directly into sustainability reporting and data engineering pipelines.

• CSV Logging: Appends per-run emission data to a local CSV file, including project name, timestamp, duration, energy consumed (kWh), and emissions (CO2eq).
• Dashboard Visualization: Provides an optional web dashboard (codecarbon visualize) that renders interactive charts of cumulative emissions over time from the logged CSV data.
• Prometheus Integration: Can expose emission metrics as a Prometheus endpoint, enabling integration with existing cloud-native monitoring stacks like Grafana for real-time GreenOps dashboards.
• JSON Export: Supports exporting the final emission summary as a JSON object for programmatic consumption by CI/CD pipelines or internal carbon accounting APIs.

CodeCarbon is architected to function in ephemeral, headless compute environments common in modern MLOps workflows.

• Offline Mode: When the machine has no internet access, the tracker uses a cached local copy of the emission factors database, preventing pipeline failures in air-gapped environments.
• CI/CD Integration: Designed to run inside GitHub Actions, GitLab CI, or Jenkins pipelines to track the carbon cost of automated model retraining and report it as a build artifact.
• Logging Callbacks: Provides hooks to stream emission data to external logging services or custom data sinks, enabling integration with enterprise ELK (Elasticsearch, Logstash, Kibana) stacks.
• Stateless Operation: Each run is independent and appends to the central log, requiring no persistent daemon or database, which aligns with the stateless nature of containerized workloads.