📌 Overview

Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.

It detects your location and your device automatically before starting to export measurements to an exporter. It could be used as a CLI with already defined metrics or programmatically with the API by defining the metrics that you want to have.

Read more in this article.

📦 Where to get it

# Install Tracarbon
pip install tracarbon

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

🔌 Devices: energy consumption

🎮 GPU: power tracking

📡 Exporters

🗺️ Locations

⚙️ Configuration

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

🔎 Usage

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 🚀

Command Line

tracarbon run

Prometheus with Kubernetes containers

tracarbon run --exporter-name Prometheus --containers

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

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.

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.

💻 Development

Local: using uv

make init
make test-unit

🛡️ Licence

Apache License 2.0

📚 Documentation

The documentation is hosted here: https://fvaleye.github.io/tracarbon/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