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

measure transforms archiving observation conversion compose generic animals projection optimize

Last synced: about 14 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 (about 3 years ago)
Default Branch: main
Last Pushed: 2025-03-10T08:58:09.000Z (about 2 months ago)
Last Synced: 2025-04-17T22:43:54.933Z (9 days ago)
Topics: carbon-footprint, electricity-consumption, energy, energy-consumption, energy-efficiency, sustainability
Language: Python
Homepage: https://fvaleye.github.io/tracarbon/documentation/
Size: 5.57 MB
Stars: 101
Watchers: 4
Forks: 7
Open Issues: 8
Releases: 31
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS

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

📦 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

Devices	Description
Mac	✅ Global energy consumption of your Mac (must be plugged into a wall adapter).
Linux	⚠️ Only with RAPL. See #1. It works with containers on Kubernetes using the Metric API if available.
Windows	❌ Not yet implemented. See #184.

Cloud Provider	Description
AWS	✅ Use the hardware's usage with the EC2 instances carbon emissions datasets of cloud-carbon-coefficients.
GCP	❌ Not yet implemented.
Azure	❌ 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	Source
Worldwide	Get the latest co2g/kwh in near real-time using the CO2Signal or ElectricityMaps APIs. See here for the list of available zones.	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

⚙️ 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.

🔎 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

API

from tracarbon import TracarbonBuilder, TracarbonConfiguration

configuration = TracarbonConfiguration() # Your configuration
tracarbon = TracarbonBuilder(configuration=configuration).build()
tracarbon.start()
# Your code
tracarbon.stop()

with tracarbon:
    # Your code

report = tracarbon.report() # Get the report

💻 Development

Local: using Poetry

make init
make test-unit

🛡️ Licence

Apache License 2.0

📚 Documentation

The documentation is hosted here: https://fvaleye.github.io/tracarbon/documentation

Owner metadata

Name: Florian Valeye
Login: fvaleye
Email:
Kind: user
Description:
Website: https://fvaleye.github.io/
Location: France
Twitter:
Company: @BackMarket
Icon url: https://avatars.githubusercontent.com/u/19929573?u=7cf8664b3a22efcfd0b8b0c7db144d9facda29c9&v=4
Repositories: 14
Last ynced at: 2024-06-11T15:40:20.132Z
Profile URL: https://github.com/fvaleye

GitHub Events

Total

Create event: 45
Issues event: 2
Release event: 4
Watch event: 3
Delete event: 47
Issue comment event: 38
Push event: 38
Pull request event: 87
Fork event: 1

Last Year

Create event: 45
Issues event: 2
Release event: 4
Watch event: 3
Delete event: 47
Issue comment event: 38
Push event: 38
Pull request event: 87
Fork event: 1

Committers metadata

Last synced: 4 days ago

Total Commits: 327
Total Committers: 5
Avg Commits per committer: 65.4
Development Distribution Score (DDS): 0.239

Commits in past year: 69
Committers in past year: 3
Avg Commits per committer in past year: 23.0
Development Distribution Score (DDS) in past year: 0.159

Name	Email	Commits
dependabot[bot]	4****]	249
fvaleye	f**e@g**m	74
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: 11
Total pull requests: 432
Average time to close issues: about 2 months
Average time to close pull requests: 4 days
Total issue authors: 6
Total pull request authors: 4
Average comments per issue: 1.09
Average comments per pull request: 0.28
Merged pull request: 325
Bot issues: 0
Bot pull requests: 357

Past year issues: 1
Past year pull requests: 114
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 11 days
Past year issue authors: 1
Past year pull request authors: 3
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.6
Past year merged pull request: 54
Past year bot issues: 0
Past year bot pull requests: 105

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/fvaleye/tracarbon

Top Issue Authors

corentinbettiol (3)
fvaleye (3)
fatma-laribi (2)
maxbaiw29 (1)
patricgruber (1)
AceWang377 (1)

Top Pull Request Authors

dependabot[bot] (357)
fvaleye (73)
baiello (1)
patricgruber (1)

Top Issue Labels

enhancement (6)
bug (2)
help wanted (2)
energy-consumption (2)
good first issue (1)

Top Pull Request Labels

dependencies (365)
enhancement (36)
release (15)
bug (10)
documentation (8)
energy-consumption (2)

Package metadata

Total packages: 1
Total downloads:
- pypi: 781 last-month
Total dependent packages: 0
Total dependent repositories: 1
Total versions: 31
Total maintainers: 1

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.7.4 (published 4 months ago)
Last Synced: 2025-04-25T13:04:40.684Z (1 day ago)
Versions: 31
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 781 Last month
Rankings:
- Dependent packages count: 10.002%
- Average: 17.253%
- Downloads: 20.038%
- Dependent repos count: 21.718%
Maintainers (1)
- fvaleye

Dependencies

.github/workflows/build.yml actions

abatilo/actions-poetry v2 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/codeql-analysis.yml actions

actions/checkout v3 composite
github/codeql-action/analyze v2 composite
github/codeql-action/init v2 composite

.github/workflows/release.yml actions

abatilo/actions-poetry v2 composite
actions/checkout v3 composite
actions/setup-python v4 composite

Dockerfile docker

python 3.8-buster build

poetry.lock pypi

Babel 2.11.0 develop
GitPython 3.1.30 develop
Jinja2 3.1.2 develop
MarkupSafe 2.1.1 develop
PyYAML 6.0 develop
Pygments 2.14.0 develop
Sphinx 5.3.0 develop
alabaster 0.7.13 develop
bandit 1.7.4 develop
beautifulsoup4 4.11.1 develop
black 22.12.0 develop
commonmark 0.9.1 develop
coverage 7.0.5 develop
docutils 0.19 develop
exceptiongroup 1.1.0 develop
execnet 1.9.0 develop
future 0.18.3 develop
gitdb 4.0.10 develop
imagesize 1.4.1 develop
iniconfig 2.0.0 develop
isort 5.11.4 develop
mando 0.6.4 develop
mypy 0.991 develop
mypy-extensions 0.4.3 develop
packaging 23.0 develop
pathspec 0.10.3 develop
pbr 5.11.1 develop
platformdirs 2.6.2 develop
pluggy 1.0.0 develop
pprintpp 0.4.0 develop
pydata-sphinx-theme 0.12.0 develop
pytest 7.2.1 develop
pytest-asyncio 0.20.3 develop
pytest-clarity 1.0.1 develop
pytest-cov 4.0.0 develop
pytest-mock 3.10.0 develop
pytest-xdist 3.1.0 develop
pytz 2022.7.1 develop
radon 5.1.0 develop
rich 13.1.0 develop
six 1.16.0 develop
smmap 5.0.0 develop
snowballstemmer 2.2.0 develop
soupsieve 2.3.2.post1 develop
sphinxcontrib-devhelp 1.0.2 develop
sphinxcontrib-htmlhelp 2.0.0 develop
sphinxcontrib-jsmath 1.0.1 develop
sphinxcontrib-qthelp 1.0.3 develop
sphinxcontrib-serializinghtml 1.1.5 develop
sphinxcontrib.applehelp 1.0.2 develop
stevedore 3.5.2 develop
toml 0.10.2 develop
tomli 2.0.1 develop
typed-ast 1.5.4 develop
types-aiofiles 22.1.0.4 develop
types-requests 2.28.11.7 develop
types-ujson 5.7.0.0 develop
types-urllib3 1.26.25.4 develop
aiocache 0.12.0
aiofiles 22.1.0
aiohttp 3.8.3
aiosignal 1.3.1
async-timeout 4.0.2
asynctest 0.13.0
attrs 22.2.0
cached-property 1.5.2
certifi 2022.12.7
charset-normalizer 2.1.1
click 8.1.3
colorama 0.4.6
datadog 0.44.0
ec2-metadata 2.11.0
frozenlist 1.3.3
idna 3.4
importlib-metadata 6.0.0
loguru 0.6.0
msgpack 1.0.4
multidict 6.0.4
prometheus-client 0.15.0
psutil 5.9.4
pydantic 1.10.4
python-dotenv 0.21.0
requests 2.28.2
typer 0.7.0
typing-extensions 4.4.0
ujson 5.7.0
urllib3 1.26.14
win32-setctime 1.1.0
yarl 1.8.2
zipp 3.11.0

pyproject.toml pypi

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

Score: 12.963918490654047

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology