Metadata-Version: 2.4
Name: tracarbon
Version: 0.13.0
Summary: Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.
Author-email: Florian Valeye <fvaleye@github.com>
License-Expression: Apache-2.0
Project-URL: documentation, https://fvaleye.github.io/tracarbon/documentation/
Project-URL: repository, https://github.com/fvaleye/tracarbon
Keywords: energy,sustainability,energy-consumption,electricity-consumption,energy-efficiency,carbon-footprint,carbon-emissions
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: loguru<0.8,>=0.6
Requires-Dist: aiohttp<4.0.0,>=3.14.3
Requires-Dist: aiofiles<26.0,>=23.2
Requires-Dist: psutil>=5.9.8
Requires-Dist: orjson<4,>=3.10
Requires-Dist: pydantic<3.0.0,>=2.0
Requires-Dist: typer<0.28,>=0.16
Requires-Dist: ec2-metadata<4.0.0,>=2.14.0
Requires-Dist: requests<3.0.0,>=2.31
Requires-Dist: python-dotenv<1.3,>=0.21
Provides-Extra: datadog
Requires-Dist: datadog<0.55,>=0.44; extra == "datadog"
Provides-Extra: prometheus
Requires-Dist: prometheus-client<0.27,>=0.16; extra == "prometheus"
Provides-Extra: kubernetes
Requires-Dist: kubernetes<37.0,>=26.1; extra == "kubernetes"
Provides-Extra: dev
Requires-Dist: ty>=0.0.1a6; extra == "dev"
Requires-Dist: ruff<0.17.0,>=0.15.10; extra == "dev"
Requires-Dist: pytest<10.0.0,>=8.4.0; extra == "dev"
Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.5.0,>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "dev"
Requires-Dist: pytest-clarity<2.0.0,>=1.0.1; extra == "dev"
Requires-Dist: sphinx<10.0.0,>=7.4.7; extra == "dev"
Requires-Dist: pydata-sphinx-theme<0.20.0,>=0.14.4; extra == "dev"
Requires-Dist: toml<0.11.0,>=0.10.2; extra == "dev"
Requires-Dist: datadog<0.55,>=0.44; extra == "dev"
Requires-Dist: prometheus-client<0.27,>=0.16; extra == "dev"
Requires-Dist: bandit<2.0.0,>=1.7.9; extra == "dev"
Requires-Dist: radon<7.0.0,>=6.0.1; extra == "dev"
Requires-Dist: kubernetes<37.0,>=26.1; extra == "dev"
Requires-Dist: uv; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=3.7.0; extra == "dev"
Provides-Extra: all
Requires-Dist: tracarbon[datadog]; extra == "all"
Requires-Dist: tracarbon[prometheus]; extra == "all"
Requires-Dist: tracarbon[kubernetes]; extra == "all"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/fvaleye/tracarbon/main/logo.png" alt="Tracarbon logo" width="200">

[![Build](https://github.com/fvaleye/tracarbon/actions/workflows/build.yml/badge.svg)](https://github.com/fvaleye/tracarbon/actions/workflows/build.yml)
[![PyPI](https://img.shields.io/pypi/v/tracarbon.svg)](https://pypi.org/project/tracarbon/)
[![Documentation](https://img.shields.io/badge/docs-python-blue.svg)](https://fvaleye.github.io/tracarbon/documentation/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/fvaleye/tracarbon/blob/main/LICENSE.txt)

## 📌 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](https://medium.com/@florian.valeye/tracarbon-track-your-devices-carbon-footprint-fb051fcc9009).

## 📦 Installation

```sh
# Install Tracarbon
pip install tracarbon
```

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

## 🔎 Usage

### Command line

```sh
tracarbon run
```

### Python API

```python
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](https://app.electricitymaps.com/developer-hub/api/reference) 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](tracarbon/locations/data/co2-emission-intensity.json) and cloud regions.
To use the bundled country data without IP geolocation, choose the country explicitly:

```sh
TRACARBON_CO2SIGNAL_API_KEY= tracarbon run --country-code-alpha-iso-2 fr
```

See [file and API configuration](docs/source/usage.rst#carbon-intensity) for Python examples, refresh intervals, and API failure behavior.

### Prometheus with Kubernetes containers

```sh
tracarbon run --exporter-name Prometheus --containers
```

See the [Prometheus metric reference](docs/source/usage.rst#export-metrics) 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](https://web.eece.maine.edu/~vweaver/projects/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](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/main/data/aws-instances.csv). |
| GCP | ✅ Use the hardware's usage with the GCP [instances](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/b0032d9/data/gcp-instances-latest-2026.csv) and [coefficients](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/b0032d9/output/coefficients-gcp-use.csv) of [cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/ccf-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](https://github.com/cloud-carbon-footprint/ccf-coefficients/blob/main/data/azure-instances.csv). |

### 🎮 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](https://jsonlines.org/) with a `.jsonl` path. |
| Prometheus | Expose an HTTP endpoint for Prometheus to scrape. |
| Datadog | Send the metrics to Datadog. |

See [exporter examples](docs/source/usage.rst#export-metrics) 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](https://app.electricitymaps.com/developer-hub/api/reference) for available Electricity Maps query modes.<br><br>[CO2Signal API](https://www.co2signal.com) or [ElectricityMaps](https://app.electricitymaps.com/developer-hub/api/reference) |
| Supported countries | Latest yearly lifecycle carbon intensity of electricity for 200+ countries in the [bundled dataset](tracarbon/locations/data/co2-emission-intensity.json), used without an API key.<br><br>[Ember](https://ember-energy.org/data/yearly-electricity-data/) via [Our World in Data](https://ourworldindata.org/grapher/carbon-intensity-electricity), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
| AWS | Static file of the AWS Grid emissions factors.<br><br>[cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/grid-emissions-factors-aws.csv) |
| GCP | Static file of the GCP Grid emissions factors (2025 yearly data).<br><br>[GoogleCloudPlatform/region-carbon-info](https://github.com/GoogleCloudPlatform/region-carbon-info/blob/main/data/yearly/2025.csv) |
| Azure | Static file of the Azure Grid emissions factors.<br><br>[cloud-carbon-coefficients](https://github.com/cloud-carbon-footprint/cloud-carbon-coefficients/blob/main/data/grid-emissions-factors-azure.csv) |

## ⚙️ Configuration

Set the variables below in your environment or a `.env` file. See [configuration details](docs/source/usage.rst#configuration).

| Parameter | Description |
| --- | --- |
| `TRACARBON_CO2SIGNAL_API_KEY` | The [Electricity Maps](https://app.electricitymaps.com/developer-hub/api/reference) 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](https://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

```sh
make init
make test-unit
```

## 🛡️ Licence

[Apache License 2.0](https://raw.githubusercontent.com/fvaleye/tracarbon/main/LICENSE.txt)

## 📚 Documentation

Read the [documentation](https://fvaleye.github.io/tracarbon/documentation/).

## 📖 Cited in

- 2025-11 [Carbon Emission Quantification of Machine Learning: A Review](https://doi.org/10.1109/TSUSC.2025.3578834)
- 2025-04-25 [A Critical Analysis of Machine Learning Eco-feedback Tools through the Lens of Sustainable HCI](https://doi.org/10.1145/3706598.3713198)
- 2025-04-25 ["Should I choose a smaller model?": Understanding ML Model Selection and Its Impact on Sustainability](https://doi.org/10.1145/3706598.3713240)
- 2024-07-08 [Balancing computational chemistry's potential with its environmental impact](https://doi.org/10.1039/D4GC01745E)
- 2023-06-26 [GREENER principles for environmentally sustainable computational science](https://doi.org/10.1038/s43588-023-00461-y)
- 2023-01-19 [eco2AI: Carbon Emissions Tracking of Machine Learning Models as the First Step Towards Sustainable AI](https://doi.org/10.1134/S1064562422060230)
