Tracarbon is a Python library and CLI that tracks your device's energy consumption and estimates its carbon emissions.
It detects your device and location automatically. Run it from the command line to collect and export measurements, or use the Python API to add tracking to your application.
Read the introductory article.
# Install Tracarbon
pip install tracarbon# Install one or more exporters from the list
pip install 'tracarbon[datadog,prometheus,kubernetes]'tracarbon runfrom tracarbon import TracarbonBuilder, TracarbonConfiguration
configuration = TracarbonConfiguration() # Your configuration
tracarbon = TracarbonBuilder(configuration=configuration).build()
tracarbon.start()
# Your code
total_co2g = tracarbon.stop() # The CO2 grams emitted while it was running
with tracarbon:
... # Your code
report = tracarbon.report # Get the report
print(report.total_co2g)total_co2g is None when no host carbon emission metric was collected. The total reflects collected samples.
For the latest electricity carbon intensity, get an Electricity Maps API key and set TRACARBON_CO2SIGNAL_API_KEY in your environment or .env file, or pass co2signal_api_key to TracarbonConfiguration.
Without a key, Tracarbon uses bundled data for supported countries and cloud regions.
To use the bundled country data without IP geolocation, choose the country explicitly:
TRACARBON_CO2SIGNAL_API_KEY= tracarbon run --country-code-alpha-iso-2 frSee file and API configuration for Python examples, refresh intervals, and API failure behavior.
tracarbon run --exporter-name Prometheus --containersSee the Prometheus metric reference for metric names, labels, and units.
When running in Kubernetes, deploy Tracarbon per node and set NODE_NAME from spec.nodeName with the Downward API so container metrics are scoped to the measured node.
| Devices | Description |
|---|---|
| Mac | ✅ Apple Silicon CPU, GPU, memory and Neural Engine energy via IOReport (no sudo). Excludes display and peripherals. Fallbacks: powermetrics (sudo), then ioreg. |
| Linux | ✅ Intel and AMD power via RAPL. AMD requires kernel 5.8+ (powercap) or amd_energy (HWMON). Unreadable RAPL permits GPU-only readings. Host power and emissions remain unknown. |
| Windows | ✅ NVIDIA GPU power via nvidia-smi. CPU, memory and host totals are unavailable. |
| Cloud Provider | Description |
|---|---|
| AWS | ✅ Use the hardware's usage with the EC2 instances carbon emissions datasets of cloud-carbon-coefficients. |
| GCP | ✅ Use the hardware's usage with the GCP instances and coefficients of cloud-carbon-coefficients (Apache-2.0, 2026-04-24), generated by scripts/generate_gcp_instances.py. |
| Azure | ✅ Use the hardware's usage with the Azure instances carbon emissions datasets of cloud-carbon-coefficients. |
| GPU | Description |
|---|---|
| NVIDIA | ✅ Supported via nvidia-smi. Works on Linux, Windows, and Intel Macs. Supports multiple GPUs. |
| AMD | ✅ Supported via rocm-smi or amd-smi on Linux. Supports multiple GPUs. |
| Apple Silicon | ✅ Integrated GPU power via IOReport, without sudo. Falls back to powermetrics (requires sudo). |
| Intel | ❌ Not yet implemented. |
| Exporter | Description |
|---|---|
| Stdout | Log metrics through the application's logging handler (stderr in the CLI). |
| JSON | Write a JSON array by default, or JSON Lines with a .jsonl path. |
| Prometheus | Expose an HTTP endpoint for Prometheus to scrape. |
| Datadog | Send the metrics to Datadog. |
See exporter examples for JSON files, JSON Lines, and Prometheus scraping.
| Location | Description and source |
|---|---|
| Worldwide | Get the latest co2g/kwh in near real-time using the CO2Signal or ElectricityMaps APIs. See here for available Electricity Maps query modes. CO2Signal API or ElectricityMaps |
| Supported countries | Latest yearly lifecycle carbon intensity of electricity for 200+ countries in the bundled dataset, used without an API key. Ember via Our World in Data, CC BY 4.0 |
| AWS | Static file of the AWS Grid emissions factors. cloud-carbon-coefficients |
| GCP | Static file of the GCP Grid emissions factors (2025 yearly data). GoogleCloudPlatform/region-carbon-info |
| Azure | Static file of the Azure Grid emissions factors. cloud-carbon-coefficients |
Set the variables below in your environment or a .env file. See configuration details.
| Parameter | Description |
|---|---|
TRACARBON_CO2SIGNAL_API_KEY |
The Electricity Maps API key. The variable keeps its CO2Signal name for compatibility. |
TRACARBON_CO2SIGNAL_URL |
The carbon intensity endpoint. Defaults to the Electricity Maps https://api.electricitymaps.com/v4/carbon-intensity/latest. |
TRACARBON_EMISSION_FACTOR_TYPE |
The Electricity Maps emission factor: lifecycle (default) or direct. |
TRACARBON_METRIC_PREFIX_NAME |
Metric name prefix. Defaults to tracarbon. |
TRACARBON_INTERVAL_IN_SECONDS |
Measurement interval in seconds. Defaults to 60. |
TRACARBON_LOG_LEVEL |
Minimum log level for the CLI. Defaults to INFO. |
TRACARBON_IPINFO_TOKEN |
An optional ipinfo.io API token used for country detection from the IP address, lifting the anonymous rate limit. |
TRACARBON_KUBERNETES_NODE_NAME |
The Kubernetes node name used to scope container metrics to the node being measured. Falls back to NODE_NAME when unset. |
PROMETHEUS_ADDRESS |
The address the Prometheus exporter listens on. Defaults to ::. |
PROMETHEUS_PORT |
The port the Prometheus exporter listens on. Defaults to 8081. |
DATADOG_API_KEY |
The Datadog API key of the Datadog exporter. |
DATADOG_APP_KEY |
The Datadog application key of the Datadog exporter. |
make init
make test-unitRead the documentation.
- 2025-11 Carbon Emission Quantification of Machine Learning: A Review
- 2025-04-25 A Critical Analysis of Machine Learning Eco-feedback Tools through the Lens of Sustainable HCI
- 2025-04-25 "Should I choose a smaller model?": Understanding ML Model Selection and Its Impact on Sustainability
- 2024-07-08 Balancing computational chemistry's potential with its environmental impact
- 2023-06-26 GREENER principles for environmentally sustainable computational science
- 2023-01-19 eco2AI: Carbon Emissions Tracking of Machine Learning Models as the First Step Towards Sustainable AI