mlco2/ecologits

🌱 EcoLogits tracks the energy consumption and environmental footprint of using generative AI models through APIs.

EcoLogits – Estimating the carbon impact of generative‑AI calls

What it is – EcoLogits is a Python library that measures the energy use and greenhouse‑gas emissions of inference requests made to popular generative‑AI APIs (OpenAI, Anthropic, Cohere, Google‑GenAI, HuggingFace, Mistral AI, …). It plugs into the client code, sends the request as usual, and returns an impacts object containing estimated kWh and CO₂‑equivalent values.

Why it matters – As large language models become ubiquitous, their computational footprint grows. EcoLogits gives developers a simple way to surface that hidden cost, helping teams make more sustainable choices, report emissions, or offset usage.

Installation

pip install ecologits                # core package
pip install ecologits[openai]        # add support for a specific provider (e.g. OpenAI)

Supported providers are listed in the docs and include anthropic, cohere, google-genai, huggingface-hub, mistralai, and openai.

Basic usage

from ecologits import EcoLogits
from openai import OpenAI

EcoLogits.init(providers=["openai"])   # enable tracking for OpenAI calls
client = OpenAI(api_key="<YOUR_KEY>")

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

print("Energy consumption:", response.impacts.energy.value.mean, "kWh")
print("GHG emissions:",    response.impacts.gwp.value.mean, "kgCO2eq")

The response.impacts object provides mean (and possibly distribution) estimates for energy (kWh) and global‑warming‑potential (kg CO₂‑eq).

Key features

  • Provider‑agnostic: works with the major LLM APIs via optional extras.
  • Quantitative metrics: returns both electricity use and CO₂‑equivalent emissions.
  • Lightweight integration: only a couple of lines of code to start tracking.
  • Open‑source & community‑driven: part of the CodeCarbon non‑profit, MIT‑style MPL‑2.0 license.
  • Documentation & tooling: full docs at https://ecologits.ai, a Colab notebook, and a Discord community for support.

Who uses it – Researchers, product teams, and sustainability officers who need to audit the environmental cost of AI services.

Contributing – Guidelines and a development setup are provided in the docs (see Contributing to EcoLogits). The project welcomes contributions and is backed by several sponsors.

EcoLogits makes the hidden energy bill of generative‑AI visible, enabling more responsible development and reporting.