📌 Overview

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.

📦 Installation

# Install Tracarbon
pip install tracarbon

# Install one or more exporters from the list
pip install 'tracarbon[datadog,prometheus,kubernetes]'

🔎 Usage

Command line

tracarbon run

Python API

from 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.

Request your API key

• Go to CO2Signal and get your free API key for non-commercial use, or go to ElectricityMaps for commercial use.
• This API is used to retrieve the last known carbon intensity (in gCO2eq/kWh) of electricity consumed in your location.
• Set your API key in the environment variables, in the .env file or directly in the configuration.
• If you would like to start without an API key, it's possible, the carbon intensity will be loaded statistically from a file.
• Launch Tracarbon 🚀

Prometheus with Kubernetes containers

tracarbon run --exporter-name Prometheus --containers

Container metric names and labels

With the default metric prefix, container metrics are exposed with these Prometheus names:

Metric	Labels
tracarbon_energy_consumption_kubernetes_total	pod_name, pod_namespace, container_name, platform, containers, location, units
tracarbon_energy_consumption_kubernetes_cpu	pod_name, pod_namespace, container_name, platform, containers, location, units
tracarbon_energy_consumption_kubernetes_memory	pod_name, pod_namespace, container_name, platform, containers, location, units
tracarbon_carbon_emission_kubernetes_total	pod_name, pod_namespace, container_name, platform, containers, location, source, units
tracarbon_carbon_emission_kubernetes_cpu	pod_name, pod_namespace, container_name, platform, containers, location, source, units
tracarbon_carbon_emission_kubernetes_memory	pod_name, pod_namespace, container_name, platform, containers, location, source, units

Zero values are exported. If Kubernetes returns no pod metrics, the CLI logs No Kubernetes container metrics were collected. Host metrics are still exported.

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.

🔌 Supported devices

Hosts

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	✅ Supports Intel and AMD processors via RAPL. Intel uses the powercap interface. AMD is supported on kernel 5.8+ (powercap) or via the amd_energy driver (HWMON). Works with containers on Kubernetes using the Metric API if available.
Windows	✅ NVIDIA GPU power via nvidia-smi. CPU, memory and host totals are unavailable.

Cloud providers

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 carbon emissions datasets of cloud-carbon-coefficients.
Azure	✅ Use the hardware's usage with the Azure instances carbon emissions datasets of cloud-carbon-coefficients.

🎮 GPU power tracking

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.

📡 Exporters

Exporter	Description
Stdout	Print the metrics in Stdout.
JSON	Write the metrics in a JSON file.
Prometheus	Send the metrics to Prometheus.
Datadog	Send the metrics to Datadog.

🗺️ Locations

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
Europe	Static file created from the European Environment Agency Emission for the co2g/kwh in European countries. EEA website
AWS	Static file of the AWS Grid emissions factors. cloud-carbon-coefficients
GCP	Static file of the GCP Grid emissions factors (2024 yearly data). GoogleCloudPlatform/region-carbon-info
Azure	Static file of the Azure Grid emissions factors. cloud-carbon-coefficients

⚙️ Configuration

The environment variables can be set from an environment file .env.

Parameter	Description
TRACARBON_CO2SIGNAL_API_KEY	The api key received from CO2Signal or ElectricityMaps.
TRACARBON_CO2SIGNAL_URL	The url of CO2Signal is the default endpoint to retrieve the last known state of the zone, but it could be changed to ElectricityMaps.
TRACARBON_METRIC_PREFIX_NAME	The prefix to use in all the metrics name.
TRACARBON_INTERVAL_IN_SECONDS	The interval in seconds to wait between the metrics evaluation.
TRACARBON_LOG_LEVEL	The level to use for displaying the logs.
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.

💻 Development

Local: using uv

make init
make test-unit

🛡️ Licence

Apache License 2.0

📚 Documentation

Read the documentation.

📖 Cited in

• 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