Skip to content

CodeGreen

PyPI PyPI Downloads GitHub stars License Platform DOI

  • Precise Energy Measurement

    Hardware-level energy monitoring via RAPL (Linux), IOReport (macOS), EMI (Windows), NVML, and ROCm with sub-millisecond resolution.

    Getting Started

  • Multi-Language Support

    Python, C, C++, and Java instrumentation via Tree-sitter with config-driven extensibility.

    Examples

  • Continuous Monitoring

    codegreen monitor samples an already-running service, with cgroup_v2 per-PID attribution and a UDS annotation channel for per-request energy.

    Continuous Monitoring

  • Interactive Visualization

    Energy timeline plots with per-function breakdown, hotspot detection, and zoom/pan via Plotly.

    Reports & Visualization

  • Easy Integration

    CLI tool with JSON/CSV/Markdown output, CI/CD energy gating via --budget, and granularity control.

    Installation

Setup & Installation

Quick start guide: installing and configuring CodeGreen.

What is CodeGreen?

CodeGreen is an energy measurement tool that helps developers understand the energy consumption of their software at the function level. It uses Tree-sitter AST parsing for automatic code instrumentation and a C++ backend (NEMB) for hardware-level energy readings with minimal overhead.

Key Features

  • Energy Measurement: Per-function energy attribution via RAPL (Linux), IOReport + kpc (macOS), EMI (Windows), NVML, ROCm
  • Quick Measurement: codegreen run measures energy of any shell command with hardware-level precision
  • Continuous Monitoring: codegreen monitor samples already-running services; per-PID via cgroup_v2; per-request via UDS annotations
  • Project Profiling: codegreen project plugs into your build (Maven, Gradle, Make, plain python) for per-function attribution across multi-file projects
  • Code Analysis: Tree-sitter based static analysis across Python, C, C++, Java
  • Visualization: Interactive energy timeline with --export-plot (Plotly HTML with zoom/pan)
  • Granularity Control: Coarse mode (main only) or fine mode (all functions)
  • CI/CD Energy Gating: --budget flag to enforce energy budgets in pipelines
  • Benchmarking: Built-in benchmark suite -- 0.03% error vs perf RAPL on representative workloads

Quick Start

Get started with CodeGreen in just a few steps:

pip install codegreen

git clone https://github.com/SMART-Dal/codegreen.git
cd codegreen
./install.sh

sudo codegreen init-sensors

codegreen measure python my_script.py

codegreen run python my_script.py --repeat 10

codegreen measure python my_script.py -g fine --export-plot energy.html

codegreen monitor --pid $(pgrep -f gunicorn | head -1) -d 60 -o energy.jsonl

codegreen project python ./src -r "python main.py" -g fine

Find what you need in two clicks

I want to ... Start here Then
Measure a one-off Python or shell script Quickstart 01 Quickstart measure
Get a stable mean across N runs Examples 02 Run with repeats
Bracket regions inside a long script Python API 03 Session API
Find per-method hotspots in a Java/Python/C++ project Project Profiling 04 Java / 09 Python
Watch a running daemon or webapp Continuous Monitoring 06 host / 07 PID / 08 annotations
Integrate into CI CI/CD integration codegreen run --budget 10.0 ...
Cross-validate against perf Energy Measurement 10 CodeGreen vs perf
Add a language or contribute Architecture Contributing

What's new in 0.4.9

  • codegreen monitor / codegreen.Monitor -- continuous sampler with cgroup_v2 per-PID attribution. See Continuous Monitoring.
  • codegreen.annotate_request over a UDS socket -- per-request energy in Flask/gunicorn webapps. See 08 Monitor socket.
  • codegreen run --stdin <file> -- pipe a fixed payload into the subprocess across all repeats. See CLI: run.
  • 10 worked end-to-end examples under examples/, each verified by pytest tests/test_examples.py.
  • Earlier 0.4.7 / 0.4.8 changes (schema overhaul, local-timezone display fields) are in the Changelog.

Supported Platforms

  • Linux

    Intel RAPL, NVIDIA NVML, and AMD ROCm/RAPL energy monitoring.

  • macOS

    Apple Silicon energy via IOReport (CPU/GPU/ANE/DRAM) + kpc hardware perf counters. Pre-built ARM64 wheels on PyPI.

  • Windows 11

    RAPL energy via EMI (inbox intelpep.sys driver). PKG, cores, iGPU, DRAM domains. Zero driver install.

Pre-built wheels for Linux x86_64 and macOS ARM64. Windows and other platforms: install from source.

Citing CodeGreen

If you use CodeGreen in your research, please cite:

Rajput, S., & Sharma, T. (2026). CodeGreen: Towards Improving Precision and Portability in Software Energy Measurement. arXiv preprint arXiv:2603.17924.

Full citation & BibTeX

Community

License

CodeGreen is released under the MPL 2.0 License. See the License page for details.