CodeGreen - Garage for Energy Measurement and Optimization
CodeGreen is a comprehensive tool for fine-grained energy profiling and optimization of code. It provides real-time energy measurement during code execution, identifies energy hotspots, and offers optimization suggestions to reduce energy consumption.
Installation
From PyPI (recommended for users)
pip install codegreen
Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.
Optional telemetry exporters for codegreen monitor: pip install "codegreen[otlp]" (OpenTelemetry/OTLP) or pip install "codegreen[prometheus]".
From source (recommended for development)
git clone https://github.com/SMART-Dal/codegreen.git
cd codegreen
./install.sh
# Linux: RAPL sensor access (one-time, requires sudo):
sudo ./install.sh # or: sudo codegreen init-sensors
# macOS: no setup needed, energy measurement works out of the box
Platform support
| Platform | pip install | Energy measurement | Backend |
|---|---|---|---|
| Linux x86_64 (Intel) | Pre-built wheel | Full (PKG, core, iGPU, DRAM) | RAPL via NEMB |
| Linux x86_64 (AMD) | Pre-built wheel | Full (PKG, no DRAM counter) | RAPL via NEMB |
| macOS ARM64 (Apple Silicon) | Pre-built wheel | Full (CPU, GPU, ANE, DRAM) | IOReport + kpc via NEMB |
| macOS Intel | From source | Full | IOReport via NEMB |
| Windows 11 (Intel) | From source | Full (PKG, core, iGPU, DRAM) | EMI via intelpep.sys |
| Windows 11 (AMD) | From source | Unverified | EMI may not expose AMD RAPL |
| NVIDIA GPU (any OS) | Automatic | Full (cumulative mJ) | NVML |
| Other | From source | Time-only | Fallback |
Requirements
- Python 3.9+
- Linux: kernel 5.0+, Intel/AMD CPU with RAPL support
- macOS: Apple Silicon (M1-M5) or Intel, no setup needed
- Windows 11: Intel/AMD CPU (EMI via inbox intelpep.sys driver, zero install)
- Source builds: CMake 3.16+, C++17 compiler
Usage
Measure energy of any command
codegreen run -- python script.py
codegreen run --repeat 20 --warmup 3 -- ./my_binary arg1 arg2
codegreen run --budget 10.0 --json -- python train.py # CI/CD gate
Per-function energy profiling
# Coarse mode: total program energy
codegreen measure python script.py
# Fine mode: per-function energy breakdown
codegreen measure python script.py -g fine --json
# With energy timeline plot
codegreen measure python script.py -g fine --export-plot energy.html
Project profiling, monitoring and timelines
# Per-function hotspots for a whole project (build once, run, attribute)
codegreen project python ./src -r "python main.py" -s "**/*.py"
# GPU work attributed to the launching function (torch/CUDA)
codegreen project python ./src -r "python train.py" --sync-device cuda
# Continuous host or per-PID sampling, optional OTLP / Prometheus export
codegreen monitor -d 30 -o energy.jsonl
codegreen monitor --pid 1234 --exporter prometheus --prometheus-port 9464
# Power, stacks, GC and GPU kernels on one axis for ui.perfetto.dev
codegreen timeline --nemb nemb.json --jfr run.json --out trace.json
Manual measurement from Python (Session API)
For span-based measurement of arbitrary code regions, import codegreen.Session directly — no CLI, no AST instrumentation:
import codegreen
with codegreen.Session("training-run") as s:
with s.task("data_load"):
load_data()
with s.task("train"):
model.fit(...)
with s.task("eval"):
score = model.evaluate(...)
# writes codegreen_<pid>.json with per-task energy + per-domain breakdown
Time-series sampling for power-vs-time plots (area under curve = energy):
with codegreen.Session("infer", record_time_series=True) as s:
with s.task("batch1"):
run_inference()
s.export_plot("infer.html") # interactive Plotly chart
The Session API uses the same NEMB backend as the CLI (RAPL/NVML/IOReport), supports nested + concurrent tasks, and degrades gracefully if the native library is unavailable. See API → Python for the full reference.
Static analysis (no execution)
codegreen analyze python script.py --save-instrumented
Benchmark validation (against perf RAPL ground truth)
codegreen benchmark -p nbody -p spectralnorm -l python -r 5 --profiler codegreen --profiler perf
Output formats
JSON (default for --json), CSV, Markdown table, and text summary. The JSON output is a comprehensive single source of truth containing system state, per-function energy, instrumentation points with AST-stable identifiers, and statistical analysis.
Language support
Adding a new language requires only a JSON config file in codegreen/instrumentation/configs/ plus the tree-sitter grammar. No Python code changes needed.
Currently supported: Python, C, C++, Java, JavaScript. Functions that cannot be framed safely (async, generators, coroutines, C++ constexpr) are reported as skipped_functions rather than instrumented.
Benchmarking
# Compare CodeGreen accuracy against perf RAPL ground truth
codegreen benchmark --suite benchmarksgame -l python --reps 5
# Run PerfOpt Java benchmark suite (JMH, original vs patched comparison)
codegreen benchmark --suite perfopt --dataset-dir /path/to/PerfOpt --jars-dir /path/to/jars
# Generate comparison artifacts for documentation
bash scripts/generate_comparison_artifacts.sh docs/benchmarks/
Energy Flow Graph (EFG)
CodeGreen includes an Energy Flow Graph module (codegreen/analysis/efg/) that builds energy-annotated control flow graphs from source code:
from codegreen.analysis.cfg.builder import build_per_method_cfgs
from codegreen.analysis.efg import build_efg, efg_to_dot, efg_to_text
cfgs = build_per_method_cfgs(java_source_code)
efg = build_efg(cfg_nodes, cfg_edges, "ClassName.method", "File.java", codegreen_data)
print(efg_to_text(efg)) # compact format for LLM prompts
Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-level accuracy annotations (MEASURED/ESTIMATED/INFERRED), configurable via EFGConfig.
See codegreen/analysis/efg/README.md for the module layout, a runnable example (python -m codegreen.analysis.efg.example.demo), and the current list of known issues. codegreen.analysis.cfg.energy_flow still resolves as a back-compat shim.
Architecture
- C++ NEMB backend: platform-aware energy measurement (RAPL on Linux, IOReport on macOS, EMI on Windows), sub-microsecond timestamping, background polling with lock-free ring buffers
- Python instrumentation: tree-sitter AST analysis, config-driven checkpoint insertion
- Energy Flow Graph: CFG + energy annotation for path-dependent analysis
- Benchmark harness: multi-suite support (benchmarksgame, PerfOpt), statistical analysis with t-distribution CI, IQR outlier detection, profiler comparison
CI/CD integration
# Fail pipeline if energy exceeds budget
codegreen run --budget 10.0 --json -- python tests/benchmark.py
# Exit code 1 if mean energy > 10 Joules
Upgrading
pip install --upgrade codegreen # PyPI
# or
cd codegreen && git pull && ./install.sh --upgrade # source
Citation
@article{rajput2026codegreen,
title={CodeGreen: Towards Improving Precision and Portability in Software Energy Measurement},
author={Rajput, Saurabhsingh and Sharma, Tushar},
journal={arXiv preprint arXiv:2603.17924},
year={2026}
}
License
MPL-2.0 License - see LICENSE file.
1 maintainer
Metadata
1 maintainer
Release files for codegreen 0.4.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| codegreen-0.4.9.tar.gz | 385.6 kB | Details |
Built distributions (wheels)
Total release size: 9.0 MB
Release files / codegreen-0.4.9.tar.gz
| Download URL | codegreen-0.4.9.tar.gz |
|---|---|
| Size | 385.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd1ecf833f5a3fc1edd90e974b8cd36617b7f47b7a0089cb72e560aedb85aaca
|
|
BLAKE2b-256 checksum How to use checksums |
8eea77012782b95c65c91964e95853b6b04032a97f40e82e28c5dd4a519e8d95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp313-cp313-win_amd64.whl
| Download URL | codegreen-0.4.9-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 496.0 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c2d1e8a14d53cc3916c878648b1d807a8325934ad34361d5fa0840d8d652bacc
|
|
BLAKE2b-256 checksum How to use checksums |
c28b2699b11234105a92344c469a045e43d5b6c952ba402db0031700639b2269
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.9-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 580.0 kB |
| Tags | CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fa3e0fb224e49f8af9732dff436fd7675910f436bdb13009191588a3a23e6340
|
|
BLAKE2b-256 checksum How to use checksums |
52b5af19ada76c8e07fc27a38e3d8615e8cd45b871510c32d6a951e7932c3adc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.9-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 550.6 kB |
| Tags | CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
e94c62c59e1a062c33569f3eff37bcdde04316f79430fee5a894c4da54ff17f8
|
|
BLAKE2b-256 checksum How to use checksums |
30d2f977a7d70768b240a0bc41ee9ad19317d99719beef3ec46a2617f3047b60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.9-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 383.5 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
70cd800a670eea963701c5aae017944bb25cd3308c42eeb541f34961c4f6c912
|
|
BLAKE2b-256 checksum How to use checksums |
8b1fe6012c4e4ce19f1cae3baed09018aefa80d5a35ef13e1dd23ddd027a7b2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp312-cp312-win_amd64.whl
| Download URL | codegreen-0.4.9-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 496.0 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
40e7768c69296e4734368f06faee93b71abd503d807f4de97b8a2a32b9fa80af
|
|
BLAKE2b-256 checksum How to use checksums |
4c7a1cad463665133111878defe62d978aaf343187f204e45a5bccab0ee01ea3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.9-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 580.0 kB |
| Tags | CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
b9928f6bbe3b34bd9ddb74e0f7db5970ae45e679c9e5c1bb83e73b2358733c29
|
|
BLAKE2b-256 checksum How to use checksums |
b532e531d67667aed4b137689cd923c2c47475f0e5ccfdf27e5330388cea8f96
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.9-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 550.6 kB |
| Tags | CPython 3.12 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
1b7f416dcf86816c81f526a602ff50205ba38a3de26734cb6d9ca7a3b0893084
|
|
BLAKE2b-256 checksum How to use checksums |
70cb4c7819530840a42fb4012aa46c430a2819113c6aaf119b31b9a3a33231fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.9-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 383.5 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
cd6342cba82d20da1048dbadbcfd8d6150ad26f6f1b4cabf4e12c4845517a8cc
|
|
BLAKE2b-256 checksum How to use checksums |
0abe9ea9576d718339923eeba83aaeea081fa99bf4ac5327835dd6b6e1d4bc0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp311-cp311-win_amd64.whl
| Download URL | codegreen-0.4.9-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 496.0 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
1425eb5714204f8832b2aa1c1c01f34fff404d213471574d5c23d44add7c4f0b
|
|
BLAKE2b-256 checksum How to use checksums |
60cf1b5998cb9940e095f2e5b049b6b60df1fdb6d36f3a187df3f196089756ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.9-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 580.0 kB |
| Tags | CPython 3.11 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
43e312a349dc578a5d7a68805cf80341a824dd70a9e5c991844c3c955fe47c67
|
|
BLAKE2b-256 checksum How to use checksums |
4c66633450c761db2f47f8d9cf7ce946d6251e4a7ac030c47506f8d01cd33c62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.9-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 550.6 kB |
| Tags | CPython 3.11 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
ee680908d3ac251c7842f71287348985e72c469a3c99584265b3cbb94e6e7dd1
|
|
BLAKE2b-256 checksum How to use checksums |
cea5f0a242a05606438ace616dfdaf1c06654b04504e61ba65ae3bf0021953d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.9-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 383.5 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
24737ddafdcacf1a2e9b0d43a7d02375da4f9ecf0d300df40c311f0fec47a295
|
|
BLAKE2b-256 checksum How to use checksums |
7d714a378e0be14ab0943e513b384fad8e5ee5225bc45c7a8ca1457e5e88ff25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp310-cp310-win_amd64.whl
| Download URL | codegreen-0.4.9-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 496.0 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6f50f441307f01a852266986eaab69678d612c755cfa94c6b97f06312a8e5cee
|
|
BLAKE2b-256 checksum How to use checksums |
3f0501b7ac67162f07bce941557380f06094886aa92d256716e7c182e5b49c90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.9-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 580.0 kB |
| Tags | CPython 3.10 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
b1b80218fe39f35c07429b2b561c6b13158b7fd7ea6a83be92aeb28a8f533937
|
|
BLAKE2b-256 checksum How to use checksums |
20da4035b6eca63cf0fff33ccfc67125738d70afa16ba4ab605b4ad1366ae6c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.9-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 550.6 kB |
| Tags | CPython 3.10 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
40e5b0e4c1c9b029806cdaf86ef0f4623cd40613615b75d537512dbbc2f8945d
|
|
BLAKE2b-256 checksum How to use checksums |
a6e677cb7bf98bd1063feb0fa47f8986163336bbcd11ddc08a95d0db72d574e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.9-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 383.5 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ec7972a91a6a82354e2766c5c5bd4b85d1374d45d6d5089205882cfb717f5bdc
|
|
BLAKE2b-256 checksum How to use checksums |
2bc7caf392b27536062b7134cd399af9c176f53ebc255cd1c305ea689202b605
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codegreen-0.4.9-cp39-cp39-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.9-cp39-cp39-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 580.0 kB |
| Tags | CPython 3.9 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fb00571431317bedeabb7233bc8e3b7e34ff13edd9728fd30afc3316f9e2157a
|
|
BLAKE2b-256 checksum How to use checksums |
84f66e768f1d65d9c8c9000eccbf160bfdf957df25a34bb4b25bc83cbc7b9c79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
