EcoFX

EcoFX estimates the energy use and associated carbon emissions of Python programs. Track a script or function, inspect and compare runs, export history, or browse it in a desktop dashboard.

Estimates, not meter readings: EcoFX estimates CPU-related power from configurable assumptions. By default it assumes 5 W idle power, a 45 W CPU contribution at full load, and 436 gCO2e/kWh. Process CPU is the default measurement mode. These are rough estimates and are not suitable for audited carbon accounting or precise comparisons across different hardware.

Feature list

• Track Python scripts and modules from the command line; forward arguments to the target program.
• Track functions with a decorator or code block with a context manager.
• Configure sampling interval, project name, tags, idle and CPU power, carbon intensity, CPU measurement mode, database, and summary output.
• Choose process CPU (default) or system-wide CPU sampling.
• Get estimated energy in joules and kWh, carbon emissions, average/peak CPU use, sample count, and smartphone-charge equivalent in summaries.
• Produce readable terminal output or JSON; suppress summaries for quiet runs.
• Persist runs locally in SQLite with timestamps, tags, CPU estimates, carbon assumptions, Python version, and machine name.
• Browse searchable run history in a Tkinter desktop dashboard; auto-refresh, sort columns, export displayed rows to CSV, and clear history.
• Filter command-line history by project or date range and limit/order results.
• Export all or filtered runs to CSV or JSON.
• Compare project totals and average duration; view overall or per-project aggregate statistics.
• Delete individual records or clear all history (or history before a date), with confirmation safeguards.
• Estimate energy/carbon from a supplied wattage and duration without running a workload.
• Choose a custom SQLite database path or ECOFX_DB environment variable.
• Migrate an existing .ecotrace/history.db into .ecofx/history.db without modifying the old file.
• Diagnose the installation with ecofx doctor and inspect active defaults with ecofx config.

Installation

Once published to PyPI:

python -m pip install ecofx

Requires Python 3.9 or newer. EcoFX depends on psutil and Rich. The optional GUI uses Tkinter from the Python standard library; some operating-system packages provide Tkinter separately.

Track a script

ecofx path/to/script.py

EcoFX accepts the explicit track subcommand too:

ecofx track --project image-training --poll-interval 0.25 path/to/train.py -- --epochs 5

Arguments after -- are forwarded to the target script. EcoFX options go before the script path. The short form also accepts script arguments:

ecofx path/to/train.py --epochs 5 --dataset samples.csv

The target executes in the current Python process using runpy. Its summary and run-history record are produced when it exits, including when it raises an exception. The exception is not swallowed.

Run an importable Python module instead of a file:

ecofx track --module --project nightly-job my_package.worker -- --date 2026-10-04

Equivalent module invocation:

python -m ecofx path/to/script.py

Tracking options

Use ecofx track --help for the complete live help. Common options:

Option	Description	Default
--project NAME	Friendly name stored with the run	Script or module name
--poll-interval SECONDS	CPU sampling interval; must be positive	0.2
--idle-watts WATTS	Assumed idle power	5
--max-cpu-watts WATTS	CPU power added at 100% whole-machine load	45
--carbon-intensity G_PER_KWH	Carbon intensity used for the estimate	436
--cpu-mode process|system	Sample this process or the whole system	process
--tag TAG	Attach a searchable tag; repeat as needed	None
--db PATH	SQLite database file	.ecofx/history.db
--output text|json|none	Summary output format	text
--no-save	Do not write this run to history	Save
--module	Interpret target as an importable module	Script

Examples:

ecofx track --project api-benchmark --tag staging --tag release --cpu-mode system --poll-interval 0.1 --output json benchmark.py
ecofx track --no-save --output none scratch.py
ecofx track --db C:\data\experiments.sqlite --idle-watts 8 --max-cpu-watts 65 --carbon-intensity 210 job.py

EcoFX process mode samples the current Python process and normalizes its CPU use against the machine's logical CPU count. System mode measures system-wide CPU load, which can include unrelated applications. Both modes use an idle power baseline, so results are approximate and short runs have proportionally higher uncertainty.

Track Python functions

Decorator:

from ecofx import track_emissions


@track_emissions(
    project_name="data-cleaning",
    poll_interval=0.1,
    carbon_intensity_g_per_kwh=210,
    tags=["batch", "nightly"],
)
def clean_data():
    # Your workload goes here.
    ...


clean_data()

Context manager:

from ecofx import EcoFXTracker

with EcoFXTracker(
    project_name="model-training",
    poll_interval=0.2,
    cpu_mode="process",
    tags=("experiment-7",),
):
    train_model()

EcoTracker remains available as an alias for EcoFXTracker.

Run-history commands

Show newest runs, filter by project, and choose ordering or a limit:

ecofx history
ecofx history --project training --since 2026-01-01 --until 2026-01-31 --limit 20
ecofx history --order oldest --db C:\data\experiments.sqlite

Date filters accept YYYY-MM-DD or ISO 8601 date/time values. A date-only --until includes that whole day.

Export history:

ecofx export --format csv --output runs.csv
ecofx export --format json --project training -o training.json
ecofx export --format csv > runs.csv

The default output path - writes to standard output. Export supports the same --project, --since, --until, and --db filters.

Aggregate and compare:

ecofx stats
ecofx stats --by-project
ecofx compare baseline optimized

compare accepts exact project names saved in run history. Its percentage change is calculated from total estimated energy for the two projects.

Manage saved runs:

ecofx delete 14
ecofx delete 14 --yes
ecofx clear --before 2026-01-01 --yes
ecofx clear --yes

Deletion prompts before changing history unless --yes is provided.

One-off estimate

Calculate energy and carbon from a known average wattage and runtime:

ecofx estimate --watts 60 --duration 1200
ecofx estimate --watts 60 --duration 1200 --carbon-intensity 210 --output json

This command does not run code or save a history entry.

Desktop dashboard

ecofx dashboard
ecofx-gui
ecofx dashboard --db C:\data\experiments.sqlite --refresh-seconds 10

The dashboard filters projects/tags as you type, refreshes on a timer, sorts columns when their headings are clicked, shows run-level CPU and energy estimates, exports the displayed records as CSV, and can clear the history after confirmation. It opens history for the current working directory unless you supply --db.

Configuration and troubleshooting

ecofx --help
ecofx track --help
ecofx config
ecofx doctor
ecofx --version

Set ECOFX_DB to use a default database file without repeating --db:

set ECOFX_DB=C:\data\experiments.sqlite
ecofx history

On PowerShell, set it for the current shell with:

$env:ECOFX_DB = 'C:\data\experiments.sqlite'

Estimation and data notes

The simplified estimate is:

estimated watts = idle watts + (CPU utilization / 100 × max CPU watts)
energy (kWh) = accumulated joules / 3,600,000
carbon (gCO2e) = energy (kWh) × carbon intensity (gCO2e/kWh)

The default .ecofx/history.db is local to the current working directory. No account or network service is required. A detected legacy .ecotrace/history.db is copied on first initialization; EcoFX leaves the legacy file intact.

License

No license has been declared for this project yet.