https://github.com/zwony/ecotrace
A lightweight Python library to measure the carbon footprint of your code
https://github.com/zwony/ecotrace
carbon-footprint climate co2 energy-efficiency green-software profiling python sustainability
Last synced: about 2 months ago
JSON representation
A lightweight Python library to measure the carbon footprint of your code
- Host: GitHub
- URL: https://github.com/zwony/ecotrace
- Owner: Zwony
- License: mit
- Created: 2026-03-16T13:04:02.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T08:36:48.000Z (about 2 months ago)
- Last Synced: 2026-04-19T10:26:37.811Z (about 2 months ago)
- Topics: carbon-footprint, climate, co2, energy-efficiency, green-software, profiling, python, sustainability
- Language: Python
- Homepage:
- Size: 6.15 MB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.MD
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.MD
- Security: SECURITY.MD
Awesome Lists containing this project
README
# EcoTrace
### High-Precision Energy and Emissions Instrumentation
---
**v0.8.0 is now live!** Includes new CLI profiling, JSON export API, and enhanced hardware detection.
---
**EcoTrace is a lightweight library for granular carbon footprint measurement of Python applications. No configuration files, no background services—just real-time hardware-level transparency.**
Real-time monitoring · 50+ Global Zones · AI-powered insights · Zero-configuration
[](https://pypi.org/project/ecotrace/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/ecotrace)
[](https://marketplace.visualstudio.com/items?itemName=ecotrace-team.ecotrace-monitor)
> [!TIP]
> **VS Code Extension:** Monitor application carbon footprint in real-time during development. [Download here](https://marketplace.visualstudio.com/items?itemName=ecotrace-team.ecotrace-monitor).
*Function-level carbon measurement with real-time monitoring*
---
## Quick Install
```bash
pip install ecotrace
```
---
## Quick Start
### Option 1: Zero-Code Profiling (CLI)
Measure any script without changing a single line of code:
```bash
ecotrace run my_script.py
```
### Option 2: Programmatic Tracking (Library)
Decorate functions for granular instrumentation:
```python
from ecotrace import EcoTrace
# region_code: Use ISO 3166-1 alpha-2 (e.g., US, TR, DE). See docs/SUPPORT.md for full list.
eco = EcoTrace(region_code="US")
@eco.track
def my_function():
# Your heavy processing here
pass
my_function()
# Export audit-ready reports or check cumulative totals
eco.generate_pdf_report("carbon_audit.pdf")
print(f"Total Carbon Emitted: {eco.total_carbon} gCO2")
```
### Expected Output
When initialized, EcoTrace performs automated hardware detection:
```text
---------------------------------
--- EcoTrace v0.8.0 Initialized ---
Region : US (367 gCO2/kWh)
CPU : 13th Gen Intel Core i9-13900K
TDP : 125.0W
Monitoring: Active (50ms sampling)
---------------------------------
```
---
## Why EcoTrace?
| Feature | **EcoTrace** | CodeCarbon | CarbonTracker |
|---|:---:|:---:|:---:|
| **Sampling Interval** | **50ms** | 15s | Per Epoch |
| **Isolation** | **Process-scoped** | System-wide | System-wide |
| **Dependencies** | **Zero (Core)** | 10+ (Pandas, etc.) | 5+ |
| **Async Support** | **Native** | Limited | No |
- **Deep Transparency:** Derived from verified manufacturer TDP specifications rather than category averages.
- **Fail-Safe Architecture:** Guaranteed application continuity even if hardware drivers or API keys are missing.
- **Actionable AI:** Integrates with Google Gemini to provide specific code optimization advice (optional).
---
## Documentation
- [**Architecture and Science**](docs/ARCHITECTURE.md) — How the energy model and process isolation work.
- [**Advanced Usage**](docs/USAGE.md) — GPU tracking, AI insights, benchmarks, and comparison tables.
- [**Support and Reference**](docs/SUPPORT.md) — Troubleshooting, region codes, and hardware compatibility.
---
## Contributing
We welcome contributions! Please see our [**CONTRIBUTING.MD**](CONTRIBUTING.MD) for guidelines on reporting bugs, suggesting features, or contributing hardware data.
---
## Community
[](https://discord.gg/hs58XXb3Uq)
[CHANGELOG.md](CHANGELOG.md) · [SECURITY.MD](SECURITY.MD)
---
## Author and License
**Emre Ozkal** — [GitHub](https://github.com/Zwony) · [ecotraceteam@gmail.com](mailto:ecotraceteam@gmail.com)
MIT License — Use it however you like.
*Developed for sustainable software development practices.*