# EcoLogits: estimating the energy and carbon footprint of generative AI API calls

> EcoLogits is a Python library that wraps supported generative AI clients and attaches energy, GHG and water estimates to each response. It is aimed at developers who already call hosted models and want per-call numbers rather than a data-centre total.

**mlco2/ecologits** — 🌱 EcoLogits tracks the energy consumption and environmental footprint of using generative AI models through APIs.

- Repository: https://github.com/mlco2/ecologits
- Website: https://ecologits.ai/
- Stars: 341 · Forks: 34
- Language: Python
- License: MPL-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mlco2-ecologits

## The problem EcoLogits targets: per-call footprint for hosted models

Self-hosted inference has an obvious measurement point. You control the GPU, you can read power draw, and tools such as CodeCarbon, the non-profit project EcoLogits belongs to, instrument the machine. Hosted APIs remove all of that. You send a prompt to a vendor endpoint and get text back, with no visibility into which accelerator ran the request, how long it took, or which grid supplied the electricity.

EcoLogits addresses that gap by estimating rather than measuring. The README frames the project as tracking "the energy consumption and environmental impacts of using generative AI models through APIs." The audience is developers who already call those APIs from Python and want a number attached to each response, not a facility-level report compiled after the fact.

This is a deliberate scope choice, and it defines both the usefulness and the ceiling of the library. A per-call estimate is enough to compare two prompts, two models or two providers inside the same application. It is not an audit figure.

## How EcoLogits hooks into provider SDKs

The mechanism is runtime interception, not a separate client. You call EcoLogits.init with a list of providers, and the library patches the corresponding SDK so that responses come back carrying an impacts attribute. The README example shows the shape of the result: response.impacts.energy.value.mean in kWh and response.impacts.gwp.value.mean in kgCO2eq.

The .value.mean path is worth noticing. Impacts are not reported as a single scalar but as a distribution-like object with a mean, which reflects that the underlying estimate combines uncertain inputs such as hardware type, utilisation and grid carbon intensity. The repository depends on wrapt, a wrapping library, alongside pydantic and packaging, which is consistent with monkey-patching SDK call paths and validating the resulting impact models.

Supported providers, per the README, are anthropic, cohere, google-genai, huggingface-hub, mistralai and openai. Each is an optional extra rather than a core dependency, so the base install stays small. The documentation site at ecologits.ai carries the provider list and the methodology behind the estimates; the README itself does not reproduce the formulas.

## Installing EcoLogits and reading your first impact estimate

The base package installs from PyPI. The README gives a single command, and provider integrations are pulled in through extras so you only carry the SDK you actually use.

```bash
pip install ecologits
pip install ecologits[openai]
```

After that, initialise the instrumentation before creating your client. The README passes the provider list explicitly, which keeps the patching limited to the SDKs you name.

```python
from ecologits import EcoLogits
from openai import OpenAI

EcoLogits.init(providers=["openai"])

client = OpenAI(api_key="<OPENAI_API_KEY>")
```

A normal chat completion call then returns a response whose impacts attribute carries the estimates. The README prints the mean energy in kWh and the mean global warming potential in kgCO2eq.

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a funny joke!"}],
)

print(f"Energy consumption: {response.impacts.energy.value.mean} kWh")
print(f"GHG emissions: {response.impacts.gwp.value.mean} kgCO2eq")
```

What you should see is two floating point numbers. The energy figure will be small, since a single chat completion draws far less than a kilowatt-hour; the unit is kWh, so expect a value with several leading zeros after the decimal point. If the impacts attribute is missing, the usual cause is that the provider was not passed to EcoLogits.init or that the matching extra was not installed.

## Where the estimates stop being trustworthy

The library is honest about its own framing in the name: these are estimates. Everything downstream inherits the uncertainty of assumptions the library cannot observe from a client process. You do not know the serving hardware, the batch size the vendor used, the data centre's power usage effectiveness, or the marginal carbon intensity of the grid at the moment of the request. The mean value smooths over all of that.

That makes EcoLogits a poor fit for external reporting. If you need a number that survives scrutiny in a sustainability disclosure, a per-call estimate derived from public assumptions will not carry the same weight as metered consumption on hardware you operate. The project's own documentation is the place to check which assumptions apply to a given provider, and the README does not summarise them.

The second constraint is coverage. Only the six listed providers are supported. If your application calls a vendor outside that list, or routes through a gateway or proxy that hides the underlying SDK, the interception has nothing to attach to. Self-hosted inference is also outside the design: there the measurement problem is different and CodeCarbon, the parent project, is the more natural tool.

## EcoLogits compared with CodeCarbon

The two projects come from the same non-profit and answer different questions, which makes the comparison unusually clean. CodeCarbon instruments the machine your code runs on, reading hardware power draw and multiplying by a grid carbon intensity for the region, which suits training runs, batch jobs and self-hosted inference on hardware you control.

EcoLogits assumes you control nothing. It estimates from the outside, using the request characteristics it can see (the model, the token counts, the provider) and published assumptions about how that provider serves traffic. The trade is precision for reach: CodeCarbon gives you a measurement of your own machine, EcoLogits gives you an estimate of someone else's.

If your workload is a fine-tuning run on a rented GPU, CodeCarbon is the right instrument and EcoLogits has nothing to intercept. If your workload is a production service that fans out to three hosted model vendors, the reverse holds. Running both is reasonable when an application does local embedding work and remote generation, but they will report in different units and with different confidence, so summing them into one figure is a mistake.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-08-09. Releases are frequent enough to suggest ongoing work: 0.11.1 on 2026-07-07, 0.11.0 on 2026-06-17 and 0.10.2 on 2026-06-04. The version in pyproject.toml is 0.11.1, and the project supports Python 3.10 through 3.14, which is a wide window for a library that patches other SDKs.

That patching is the main upgrade cost. Each optional dependency is pinned with an upper bound, for example openai>=1.66.0,<3.0.0 and anthropic>=0.45.2,<1.0.0. When a provider SDK ships a breaking release, EcoLogits needs a corresponding update before the extra can be widened. If you pin your provider SDK aggressively and EcoLogits lags, you can end up with a resolver conflict rather than a runtime error, which is easier to diagnose but still blocks the upgrade. The Makefile shows the development flow (uv sync --all-extras --all-groups, uv run pytest), and the test suite uses recorded HTTP interactions, which is a sensible approach for a library whose behaviour depends on external APIs.

Licensing is Mozilla Public License 2.0, a file-level copyleft. Modifications to EcoLogits' own files must be published under the same licence, while code you write that merely imports the library is unaffected. That is a summary of the licence's structure, not legal advice; check the MPL-2.0 text for your situation.

## Conclusion

Adopt EcoLogits if you already call a supported hosted provider from Python and want per-response energy, GHG and water estimates attached to the objects you already handle. Skip it if you self-host models, if your provider is not on the supported list, or if you need numbers you can defend as measurements rather than estimates. Before relying on it, check the provider list at ecologits.ai, confirm the optional extra you install matches your SDK version range, and read the methodology page to see which assumptions sit behind the mean values.

## FAQ

### Does EcoLogits measure energy consumption or estimate it?

It estimates. The README describes the library as tracking and estimating environmental impacts of API-based inference, and the returned values are means rather than readings from the serving hardware, which the client cannot observe.

### Which providers does EcoLogits support?

The README lists anthropic, cohere, google-genai, huggingface-hub, mistralai and openai, each installed as an optional extra such as ecologits[openai]. The documentation site carries the full provider list.

### How do I install EcoLogits for OpenAI?

Run pip install ecologits[openai], then call EcoLogits.init(providers=["openai"]) before creating your OpenAI client. The README gives both steps in its usage example.

### Can I use EcoLogits for a self-hosted model?

The library targets generative AI models accessed through provider APIs, so self-hosted inference falls outside its design. CodeCarbon, the non-profit project EcoLogits belongs to, is the tool aimed at measuring hardware you operate.

## Sources

- [License: MPL-2.0](https://github.com/mlco2/ecologits/blob/main/LICENSE)
- [mlco2/ecologits on GitHub](https://github.com/mlco2/ecologits)
- [Project website](https://ecologits.ai/)
- [README](https://github.com/mlco2/ecologits/blob/main/README.md)
- [Releases](https://github.com/mlco2/ecologits/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mlco2-ecologits