EcoLogits: Estimating Energy and Carbon for Hosted LLM API Calls
🌱 EcoLogits tracks the energy consumption and environmental footprint of using generative AI models through APIs.
At a glance
- What is it?
- EcoLogits is a Python library that wraps supported generative AI SDKs and attaches estimated energy, GHG and water figures to each API response. It is useful for reporting and comparison, but every number it produces is a model-based estimate, not a measurement.
- Who is it for?
- Adopt EcoLogits if you already call a supported hosted provider and need per-request environmental figures inside an existing Python application, particularly for internal reporting or comparative experiments. Do not adopt it if you need audited numbers for a public sustainability disclosure, if you run models on your own hardware, or if your provider is not on the supported list.
- Can I use it commercially?
- Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 38 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap EcoLogits fills: hosted inference you cannot meter
If you run a model on your own GPU, you can put a power meter on the wall or read the device counters. If you call a hosted API, you get tokens and a bill. Nothing in the response tells you how much electricity the provider burned to produce those tokens, and providers do not publish per-request figures.
EcoLogits targets exactly that blind spot. It is a Python library that instruments supported provider SDKs and attaches an estimated impact object to each response. The README's example prints two values after a chat completion: energy in kWh and GHG emissions in kgCO2eq, both read from response.impacts. The intended audience is developers and sustainability-minded engineers who want an order-of-magnitude figure for the inference they are already paying for, not a laboratory measurement.
The project sits under the CodeCarbon non-profit umbrella, which matters for how you read its positioning. It is a reporting and awareness tool, not a billing or compliance instrument.
How the estimate is produced: interception plus a model-based calculation
The mechanism visible in the README is interception. You call EcoLogits.init(providers=["openai"]) before constructing your client. From that point, the provider SDK's request path is patched so that a normal client.chat.completions.create call returns a response carrying an extra impacts attribute. Your application code does not otherwise change: the same model name, the same messages list, the same call signature.
The impacts object is structured rather than scalar. In the README example the energy figure is read as response.impacts.energy.value.mean and the emissions figure as response.impacts.gwp.value.mean. The presence of value.mean implies a distribution object with more than one field, most plausibly an uncertainty interval alongside the central value. The README does not document the other fields, so treat that as something to confirm against the full documentation at ecologits.ai before you build a report on it.
Because the figures are derived from the request and response metadata rather than from a sensor, the accuracy of any single number depends on the underlying impact model and on how well the provider's hardware and grid assumptions match reality. That is the central trade-off of the design: zero instrumentation burden in exchange for estimates that carry model error you cannot inspect from the call site.
Installation and the provider extras that decide your dependency tree
The base install is a single command:
pip install ecologits
That gives you the core library without any provider integration. To get the instrumentation for a specific SDK you install an extra. The README gives pip install ecologits[openai] as the pattern and lists the currently supported providers as anthropic, cohere, google-genai, huggingface-hub, mistralai and openai.
This extras design has a practical consequence worth planning around. EcoLogits does not vendor the provider SDKs, so installing ecologits[openai] pulls the OpenAI Python package into your environment. If your application already pins a specific version of that SDK, the extra has to be compatible with your pin or the install will resolve to something you did not choose. Check the resolved version after installing rather than assuming your existing pin survived.
The initialisation call takes the same provider identifiers as a list: EcoLogits.init(providers=["openai"]). Only initialise the providers you actually use. Patching an SDK you never call adds import cost and a surface for version conflicts with nothing in return.
Where the numbers stop being trustworthy
The honest framing is that EcoLogits returns estimates, and the README labels them as such in its own comment. Three consequences follow.
First, the figures are per-request and model-based, so they inherit whatever assumptions the impact model makes about hardware, utilisation and grid carbon intensity. A request routed to a provider region with a cleaner grid than the model assumes will be overstated; a region with dirtier generation will be understated. Nothing in the call site tells you which case you are in.
Second, the library only covers hosted APIs from supported providers. Self-hosted inference, local models, and any provider outside that list are out of scope. If your workload is mostly on your own hardware, EcoLogits is the wrong tool and CodeCarbon, from the same non-profit, is the direct one.
Third, the response object exposes a mean inside a value wrapper. If you aggregate thousands of requests and report a single total, you are summing central estimates and discarding the uncertainty the wrapper appears to carry. That is a defensible choice for internal dashboards and a poor one for anything published as an environmental claim.
EcoLogits and CodeCarbon are not substitutes
The obvious alternative is CodeCarbon, and the relationship is worth stating plainly because the two are often mentioned together and they measure different things. EcoLogits is part of the CodeCarbon non-profit, so this is a sibling comparison rather than a competitive one.
CodeCarbon targets code you run yourself. It estimates the emissions of a training run or an inference process by observing the machine executing it, which means it can see actual hardware utilisation on hardware you control. That is a stronger basis for a number, and it is also entirely unavailable when the computation happens inside someone else's data centre.
EcoLogits inverts the constraint. It cannot see the hardware at all, so it infers impact from what crosses the API boundary, and in return it works for the hosted inference that CodeCarbon cannot reach. The practical rule: if you own the GPU, use CodeCarbon. If you rent intelligence through an API, EcoLogits is the only one of the two that applies. Using both in the same organisation is coherent, provided you do not add the two sets of figures together as if they measured the same thing.
Maintenance, release cadence and the MPL-2.0 terms
The release history shows a steady cadence rather than a frozen one: 0.10.2 in early June 2026, 0.11.0 in mid June, and 0.11.1 in early July, with repository activity continuing into August 2026. The version numbers are still in the 0.x range, which by convention signals that the public interface may change between minor releases. The impacts object you read in your code is part of that interface.
That has a direct cost implication for anyone embedding EcoLogits in a production reporting pipeline. A minor version bump can change attribute names or the shape of the value wrapper, and your reporting code breaks silently or loudly depending on how you read the fields. Pin the version in your requirements file and read the release notes before bumping.
On licensing, the project is under the Mozilla Public License 2.0. MPL-2.0 is a file-level copyleft licence: modifications you make to EcoLogits' own source files must be made available under the same licence, while separate code that merely imports the library is not pulled into that obligation. The common case of calling EcoLogits from a proprietary application is therefore generally compatible with the licence, but the boundary is a legal question and not one to settle from a README. If you plan to fork the library or patch its internals and ship that, get the specifics reviewed.
Editorial conclusion
Adopt EcoLogits if you already call a supported hosted provider and need per-request environmental figures inside an existing Python application, particularly for internal reporting or comparative experiments. Do not adopt it if you need audited numbers for a public sustainability disclosure, if you run models on your own hardware, or if your provider is not on the supported list. Before committing, verify three things: that the provider extra you need installs cleanly on your Python version, that your SDK call path is one the instrumentation actually patches, and that the mean values returned under response.impacts are precise enough for the decision you are making. If you need a measured figure rather than an estimate, use CodeCarbon on hardware you control instead.
Community notes