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.
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
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 spectralnorm -l python -r 5 --profilers codegreen 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 config exists but is not yet exposed via CLI.
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/cfg/) that builds energy-annotated control flow graphs from source code:
from codegreen.analysis.cfg.builder import build_per_method_cfgs
from codegreen.analysis.cfg.energy_flow 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.
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.8
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.8.tar.gz | 2.0 MB | Details |
Built distributions (wheels)
Total release size: 9.1 MB
Release files / codegreen-0.4.8.tar.gz
| Download URL | codegreen-0.4.8.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1977ad9073195c3addc1536d21606ba4f8cfd624a6e5fa9fae9cd08a2c7a0719
|
|
BLAKE2b-256 checksum How to use checksums |
3476855ceebbf7f0c920751a8e49630f3ca998920435af6eeb64407cb0332102
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp313-cp313-win_amd64.whl
| Download URL | codegreen-0.4.8-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 336.3 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
da197deef9cf49f5e86f8229c74413fbbe54ac2a4617636b42f7a11f3d05fc45
|
|
BLAKE2b-256 checksum How to use checksums |
a716f8a374463f65a6ae5f3b39517cd45acf1eb3506beea4dd445db8f389bbe3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.8-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 512.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 |
4f4a06df7383737b8ce8e35dc0994e7c24d123bb88b8cc5e461d4da90974b414
|
|
BLAKE2b-256 checksum How to use checksums |
e5d753d80d9c44fbb8df1d51170ed19852b9c25d542042c45d7e20166125d389
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.8-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 482.6 kB |
| Tags | CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
eba02fbf6e7a01ac511cc6bc9142bcf963c486d93c127c51d6e1b0a511d3a00e
|
|
BLAKE2b-256 checksum How to use checksums |
fe4a3bfcbf4bd4628268ae9b971642b53baf49035a95d4868d0de01d1f9fa56d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.8-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 315.3 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b4e6780650c0669413f13bc041a92b61e11273cdb62b3debc767cfeb0ca52878
|
|
BLAKE2b-256 checksum How to use checksums |
2bc9f1ec2d26ef129886605f10d0343b38abf4d484b2fc543a55945082fefd59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp312-cp312-win_amd64.whl
| Download URL | codegreen-0.4.8-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 336.3 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b99f74b2cc75cf4a7e51b2aeb5fbe29e31fcd6ece5a8f0de1498462eaa8ff6bd
|
|
BLAKE2b-256 checksum How to use checksums |
1400868169b43645a4e681a3b8561a70cd1f05599d135f71319b3b6f41410f71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.8-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 512.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 |
736bd9eb08b72b69cb2359790dafd07d92a8c8645fff69b79292ba87e367f0c7
|
|
BLAKE2b-256 checksum How to use checksums |
21dd405be08db5863da65725da0b75e0494c9eb0374c50ae3bd1e66382d326c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.8-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 482.6 kB |
| Tags | CPython 3.12 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
3443169330ead7ba5d7cea533a0d40c5efc85559447a19504858284b927e161f
|
|
BLAKE2b-256 checksum How to use checksums |
e83c4e47159258a1d29f859ee348ade7eff517e3d8ffca0686ca999f6a0269f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.8-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 315.3 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a0e9a574cd5bc07a9bd86ac8bb2baaae52d60fa7ca44c40c34c339c2cb14ddc8
|
|
BLAKE2b-256 checksum How to use checksums |
b69c929e0de736441e754b9ba205af8ecbccd79c9852caff5105815c214142cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp311-cp311-win_amd64.whl
| Download URL | codegreen-0.4.8-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 336.3 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
420c72e28aa440c880c9951cf3444a3f47d02c965df46f5154b8fb06ff475b80
|
|
BLAKE2b-256 checksum How to use checksums |
9de9734ad7d542947c66b284fb5fb4ec0503328ca78630fd1bc35f2789c835c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.8-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 512.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 |
3dbb17c1140b18cbfecb73f227594dcb24537e8e7a4870133f2f14b6f4050b1c
|
|
BLAKE2b-256 checksum How to use checksums |
fbfa7b3ad8081f9aa0213c8bc854a0d691ba1306e656345802e48eb30076b12e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.8-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 482.6 kB |
| Tags | CPython 3.11 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
2497704a6845f6733b6efb736a192050059005e7c040dd9fe54f944ebfabc295
|
|
BLAKE2b-256 checksum How to use checksums |
486c165960ca09b881d91e47e10314f80bfe2444bbc0646ea9bbe5ca05045bc1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.8-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 315.3 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
96c1364956367ca5103c1dcf7293b22974269293f08b6006028236fe255b8ae4
|
|
BLAKE2b-256 checksum How to use checksums |
cfa7bae5f5f5b52c542644d39a86e5936f7391730b333b40cd85fb27bf5d89d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp310-cp310-win_amd64.whl
| Download URL | codegreen-0.4.8-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 336.3 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
2b53956381b983f997af11b26f7d4afcea88526a51015535aa040adfc672fc2e
|
|
BLAKE2b-256 checksum How to use checksums |
ba70f554f05afb654e134d45eac9d9fe538cee765c4ae78131856aa1eea5ff5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.8-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 512.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 |
771868be9f809865c3a23e2aa0c2a5fa39df495cebde8582d44a6e67a93df56b
|
|
BLAKE2b-256 checksum How to use checksums |
a9a6b4b18ca2596ea7725e039e222086f6d191c14dfcbd36320fb5228875e41a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | codegreen-0.4.8-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 482.6 kB |
| Tags | CPython 3.10 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
8fccc13134a63b82a19783561fb592167c177cc01c077ec9ca3a7f0802f2e850
|
|
BLAKE2b-256 checksum How to use checksums |
38c270d4eb86305b5ce182b66eca104cc4022fd80353c4ea94282e518446db89
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | codegreen-0.4.8-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 315.3 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
2993a0263aa26796fd62d0c0bce438385e64470e875b772c6dbe02f9939f2356
|
|
BLAKE2b-256 checksum How to use checksums |
ca7fcd84fcb4cb5f2da5ba7e94c9bc0d08d7f0549b5916555052b5b4ec421aa3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / codegreen-0.4.8-cp39-cp39-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | codegreen-0.4.8-cp39-cp39-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 512.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 |
f1203f7a4090aa52abbb08360c53d4c45ae7beb9200eb68c377c749f9613bf56
|
|
BLAKE2b-256 checksum How to use checksums |
63664a5d04e096d840ecff8db58a058a068ac5a9cf8fb70ca48803d270a80793
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
