Tracarbon
Tracarbon tracks your device's energy consumption and calculates your carbon emissions using your location.
https://github.com/fvaleye/tracarbon
Category: Consumption
Sub Category: Computation and Communication
Keywords
carbon-footprint electricity-consumption energy energy-consumption energy-efficiency sustainability
Keywords from Contributors
measur optimize transforms archiving generic observation conversion compose projection animals
Last synced: about 15 hours ago
JSON representation
Repository metadata
🌍 Tracarbon tracks your device's energy consumption and calculates your carbon emissions using your location.
- Host: GitHub
- URL: https://github.com/fvaleye/tracarbon
- Owner: fvaleye
- License: apache-2.0
- Created: 2022-03-11T20:22:45.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-10-06T08:25:15.000Z (12 days ago)
- Last Synced: 2026-10-09T22:35:51.336Z (9 days ago)
- Topics: carbon-footprint, electricity-consumption, energy, energy-consumption, energy-efficiency, sustainability
- Language: Python
- Homepage: https://fvaleye.github.io/tracarbon/documentation/
- Size: 10 MB
- Stars: 112
- Watchers: 3
- Forks: 7
- Open Issues: 3
- Releases: 43
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
README.md
📌 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
Owner metadata
- Name: Florian Valeye
- Login: fvaleye
- Email:
- Kind: user
- Description: Founding Engineer @altertable-ai
- Website: https://fvaleye.github.io/
- Location: France
- Twitter:
- Company: @altertable-ai
- Icon url: https://avatars.githubusercontent.com/u/19929573?u=7cf8664b3a22efcfd0b8b0c7db144d9facda29c9&v=4
- Repositories: 25
- Last ynced at: 2026-10-10T20:24:36.946Z
- Profile URL: https://github.com/fvaleye
GitHub Events
Total
- Create event: 87
- Delete event: 85
- Fork event: 1
- Issue comment event: 53
- Issues event: 3
- Pull request event: 147
- Pull request review event: 16
- Push event: 140
- Release event: 10
- Watch event: 6
Last Year
- Create event: 22
- Delete event: 25
- Issue comment event: 3
- Pull request event: 31
- Pull request review event: 4
- Push event: 63
- Release event: 3
- Watch event: 1
Committers metadata
Last synced: 1 day ago
Total Commits: 445
Total Committers: 5
Avg Commits per committer: 89.0
Development Distribution Score (DDS): 0.306
Commits in past year: 84
Committers in past year: 2
Avg Commits per committer in past year: 42.0
Development Distribution Score (DDS) in past year: 0.381
| Name | Commits | |
|---|---|---|
| dependabot[bot] | 4****] | 309 |
| fvaleye | f****e@g****m | 132 |
| Patric Gruber | me@p****t | 2 |
| Brice AIELLO | b****o@m****m | 1 |
| Florian VALEYE | f****e@F****l | 1 |
Committer domains:
- me.com: 1
- patric-gruber.at: 1
Issue and Pull Request metadata
Last synced: 1 day ago
Total issues: 12
Total pull requests: 640
Average time to close issues: over 1 year
Average time to close pull requests: 5 days
Total issue authors: 7
Total pull request authors: 4
Average comments per issue: 1.08
Average comments per pull request: 0.28
Merged pull request: 457
Bot issues: 0
Bot pull requests: 528
Past year issues: 0
Past year pull requests: 48
Past year average time to close issues: N/A
Past year average time to close pull requests: about 18 hours
Past year issue authors: 0
Past year pull request authors: 2
Past year average comments per issue: 0
Past year average comments per pull request: 0.02
Past year merged pull request: 42
Past year bot issues: 0
Past year bot pull requests: 20
Top Issue Authors
- fvaleye (3)
- corentinbettiol (3)
- fatma-laribi (2)
- maxbaiw29 (1)
- AceWang377 (1)
- JosuaCarl (1)
- patricgruber (1)
Top Pull Request Authors
- dependabot[bot] (528)
- fvaleye (109)
- patricgruber (2)
- baiello (1)
Top Issue Labels
- enhancement (6)
- bug (3)
- help wanted (2)
- energy-consumption (2)
- good first issue (1)
Top Pull Request Labels
- dependencies (536)
- python (63)
- enhancement (37)
- release (23)
- bug (13)
- documentation (8)
- energy-consumption (2)
- python:uv (1)
- github_actions (1)
Package metadata
- Total packages: 2
-
Total downloads:
- pypi: 379 last-month
- Total dependent packages: 0 (may contain duplicates)
- Total dependent repositories: 1 (may contain duplicates)
- Total versions: 84
- Total maintainers: 1
proxy.golang.org: github.com/fvaleye/tracarbon
- Homepage:
- Documentation: https://pkg.go.dev/github.com/fvaleye/tracarbon#section-documentation
- Licenses: apache-2.0
- Latest release: v0.13.0 (published 20 days ago)
- Last Synced: 2026-10-17T02:06:34.228Z (1 day ago)
- Versions: 42
- Dependent Packages: 0
- Dependent Repositories: 0
-
Rankings:
- Dependent packages count: 5.395%
- Average: 5.576%
- Dependent repos count: 5.758%
pypi.org: tracarbon
Tracarbon is a Python library that tracks your device's energy consumption and calculates your carbon emissions.
- Homepage:
- Documentation: https://tracarbon.readthedocs.io/
- Licenses: Apache-2.0
- Latest release: 0.13.0 (published 20 days ago)
- Last Synced: 2026-10-17T02:09:59.072Z (1 day ago)
- Versions: 42
- Dependent Packages: 0
- Dependent Repositories: 1
- Downloads: 379 Last month
-
Rankings:
- Dependent packages count: 10.002%
- Average: 17.253%
- Downloads: 20.038%
- Dependent repos count: 21.718%
- Maintainers (1)
Dependencies
- abatilo/actions-poetry v2 composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- actions/checkout v3 composite
- github/codeql-action/analyze v2 composite
- github/codeql-action/init v2 composite
- abatilo/actions-poetry v2 composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- python 3.8-buster build
- bandit ^1.7.4 develop
- black ^22.12.0 develop
- datadog ^0.44.0 develop
- isort ^5.11.4 develop
- mypy ^0.991 develop
- prometheus-client ^0.15.0 develop
- pydata-sphinx-theme ^0.12.0 develop
- pytest ^7.2.0 develop
- pytest-asyncio ^0.20.3 develop
- pytest-clarity ^1.0.1 develop
- pytest-cov ^4.0.0 develop
- pytest-mock ^3.7.0 develop
- pytest-xdist ^3.1.0 develop
- radon ^5.1.0 develop
- sphinx ^5.3.0 develop
- toml ^0.10.2 develop
- types-aiofiles ^22.1.0 develop
- types-requests ^2.28.11 develop
- types-ujson ^5.7.0 develop
- aiocache >=0.11.1,<0.13.0
- aiofiles ^22.1.0
- aiohttp ^3.8.1
- datadog ^0.44.0
- ec2-metadata ^2.10.0
- loguru ^0.6.0
- msgpack ^1.0.4
- prometheus-client ^0.15.0
- psutil ^5.9.1
- pydantic ^1.9.1
- python ^3.7
- python-dotenv ^0.21.0
- typer >=0.4.1,<0.8.0
- ujson ^5.3.0
- 106 dependencies
Score: 12.297169415924051