Linting a Python Project
Run carbonah lint on a Django project to find carbon-inefficient patterns:
Terminal
$ carbonah lint ./myproject/src
CARBONAH — Static Code Analysis
Files scanned : 24
Findings : 5 (3 warnings, 2 infos)
By rule : E002: 2 E003: 1 E005: 2
warning[E002]: N+1 query — database query inside a loop
--> src/api/orders.py:34:12
|
33 | for order in orders:
34 | items = db.query("SELECT * FROM items ...")
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= suggestion: Use a JOIN or batch query
= carbon: 3.7-7.2x more energy per request at scale
warning[E003]: Unbounded query — no LIMIT clause
--> src/api/users.py:18:5
|
18 | users = db.query("SELECT * FROM users")
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= suggestion: Add LIMIT or use pagination
tip: Use --fail-on E002 to gate CI on N+1 queries
Scorecard: Add --format markdown to generate a CARBONAH.md scorecard you can commit to your repo.
Analysing Dependencies
Scan a requirements.txt to find oversized or unnecessary packages:
Terminal
$ carbonah analyse requirements.txt
CARBONAH — Dependency Analysis
File : requirements.txt
Ecosystem : Python
Packages : 9 direct
Issues : 2
[D001] cryptography — OVERSIZED
Size : 20.0 MB
Fix : pip install PyJWT rsa
Saving : 19.5 MB — 97% reduction
[D003] pytest — DEV-IN-PROD
Fix : Move to dev dependencies
Measuring Any Command
Wrap any executable with carbonah measure -- to calculate its carbon intensity. The -- separates carbonah flags from your command.
Measure a Python app
Terminal
$ carbonah measure -- python app.py
CARBONAH — SCI Measurement
Command : python app.py
Runtime : 1.24s
Hardware : Apple MacBook Air M2 (8W TDP)
Carbon Breakdown
Energy (E) : 0.0000028 kWh
Grid intensity (I): 928 gCO2eq/kWh [ZA]
Operational (O) : 0.0026 gCO2eq
Embodied (M) : 0.0001 gCO2eq
SCI SCORE : 0.0027 gCO2eq/run Grade: A
Measure a compiled binary
Terminal
$ carbonah measure -- ./myapp --port 8080
Measure a build with a specific region
Terminal
$ carbonah measure --region ZA -- cargo build --release
# Uses South Africa's grid intensity (928 gCO2eq/kWh)
Measure a Node.js server startup
Terminal
$ carbonah measure -- npm start
Measure a test suite with CI gating
Terminal
$ carbonah measure --fail-on 100 -- ./run-tests.sh
# Exits non-zero if SCI exceeds 100 gCO2eq/run
It works with anything: If you can run it in a terminal, Carbonah can measure it — Python scripts, compiled binaries, Docker builds, PHP servers, test suites, shell scripts.
Session Tracking
Track your development machine's carbon emissions over a coding session:
Terminal
# Start tracking at the beginning of your work day
$ carbonah session start
* Session started — sampling every 30s
# Check in during the day
$ carbonah session status
* Running -- 2h 14m -- 0.87 gCO2eq so far
# Stop at the end of the day
$ carbonah session stop
CARBONAH — Session Report
Status : Completed
Duration : 8h 12m
Hardware : Apple MacBook Air M2 (8W TDP)
Samples : 984 (every 30s)
Avg CPU : 14%
Carbon Breakdown
Energy (E) : 0.0092 kWh
Grid intensity (I): 928 gCO2eq/kWh [ZA]
Operational (O) : 8.54 gCO2eq
Embodied (M) : 0.42 gCO2eq
SESSION TOTAL : 8.96 gCO2eq Grade: B
Extrapolations
Per hour : 1.09 gCO2eq
Per 8hr day : 8.96 gCO2eq
Per year (1 dev): 2.32 kgCO2eq
Team of 5/year : 11.60 kgCO2eq
CI Integration
Add Carbonah to your GitHub Actions pipeline to gate merges on carbon scores:
name: Carbon Check
on: [push, pull_request]
jobs:
carbonah:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Carbonah
run: curl -fsSL https://carbonah.dev/install.sh | sh
- name: Lint for carbon patterns
run: carbonah lint ./src --fail-on E002
- name: Analyse dependencies
run: carbonah analyse requirements.txt
- name: Measure test suite
run: carbonah measure --fail-on 100 -- pytest
Fail fast: Use --fail-on to set thresholds. The CI step exits non-zero when the threshold is exceeded, blocking the merge.
CARBONAH.md Scorecard
Generate a markdown scorecard to commit alongside your code:
Terminal
$ carbonah lint ./src --format markdown
✓ CARBONAH.md written to ./src/CARBONAH.md
The scorecard includes your project's carbon grade, summary metrics, findings by rule, and detailed issue breakdowns with code snippets and fix suggestions. Track your grade over time by committing CARBONAH.md to your repository.