📌 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.
Carbon intensity API
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 fr
See file and API configuration for Python examples, refresh intervals, and API failure behavior.
Prometheus with Kubernetes containers
tracarbon run --exporter-name Prometheus --containers
See 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.
🔌 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 | ✅ 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 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 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 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 | 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.
🗺️ 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 |
| 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 |
⚙️ Configuration
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. |
💻 Development
Local: using uv
make init
make test-unit
🛡️ Licence
📚 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
1 maintainer
Metadata
1 maintainer
Release files for tracarbon 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tracarbon-0.13.0.tar.gz | 90.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tracarbon-0.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 183.5 kB
Release files / tracarbon-0.13.0.tar.gz
| Download URL | tracarbon-0.13.0.tar.gz |
|---|---|
| Size | 90.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d23cf66259ce1f1237ad0cf38f33bd1cca7c967c09fdd0ffc571613c0a85f70
|
|
BLAKE2b-256 checksum How to use checksums |
705e2e430334b4ba16e07f434a29b7e59113bb0b07413c1cb6702d9da408dd53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / tracarbon-0.13.0-py3-none-any.whl
| Download URL | tracarbon-0.13.0-py3-none-any.whl |
|---|---|
| Size | 93.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a40d50564584f7cdd8a3ed842dc7f281666ba08ca009b87a03417ac885c1804
|
|
BLAKE2b-256 checksum How to use checksums |
54c2b85248d489fe289598f9e6a76035e8b8873319edf6be8f400c76bb0521ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
