llm-carbon-calculator

A lightweight, dependency-free Python library for estimating the carbon footprint of Large Language Model (LLM) API usage, following the Green Software Foundation SCI methodology.

Features

• Zero runtime dependencies
• Accepts total_api_requests and total_llm_tokens as inputs
• Outputs:
  • Total Emissions — total carbon emissions in kgCO2eq
  • Avg per Request — average emissions per API call (gCO2eq / request)
  • Weighted Carbon Intensity — energy-weighted average across multiple regions (gCO2eq / kWh)
• Multi-region support for Azure deployments
• JSON-ready API output via to_api_dict()

Installation

pip install llm-carbon-calculator

Quick Start

from llm_emissions import CarbonCalculator

calc = CarbonCalculator(
    total_api_requests=1_000,
    total_llm_tokens=500_000,
)

result = calc.calculate(region_intensity=156)

print(result.total_emissions_kg)        # kgCO2eq
print(result.avg_per_request_g)         # gCO2eq / request
print(result.weighted_carbon_intensity) # gCO2eq / kWh
print(result)                           # pretty-printed summary

Custom energy factor

calc = CarbonCalculator(
    total_api_requests=1_000,
    total_llm_tokens=500_000,
    model_energy_factor=0.000112,  # kWh per 1000 tokens
)
result = calc.calculate(region_intensity=156)

Multi-region weighted intensity

from llm_emissions.models import RegionEnergyInfo

calc = CarbonCalculator(
    total_api_requests=2_000,
    total_llm_tokens=400_000,
)
result = calc.calculate(
    region_intensity=156,
    regions=[
        RegionEnergyInfo(region_name="westeurope", tokens=300_000, region_intensity=156),
        RegionEnergyInfo(region_name="eastus",     tokens=100_000, region_intensity=380),
    ],
)
print(result.weighted_carbon_intensity)  # energy-weighted average

JSON API response

import json
print(json.dumps(result.to_api_dict(), indent=2))

Attach metadata

Extra keyword arguments are stored in result.metadata for traceability:

result = calc.calculate(
    region_intensity=156,
    model="gpt-4o",
    region="westeurope",
)
print(result.metadata)  # {'model': 'gpt-4o', 'region': 'westeurope'}

Formula

Based on the SCI (Software Carbon Intensity) specification:

emission_g = (tokens / 1000) × energy_factor × region_intensity × PUE

API Reference

CarbonCalculator(total_api_requests, total_llm_tokens, model_energy_factor=0.000056, pue=1.125)

.calculate(region_intensity, *, regions=None, **metadata) → EmissionsResult

.calculate_as_dict(...) → dict

Same parameters as .calculate(). Returns a JSON-serialisable dictionary.

EmissionsResult

RegionEnergyInfo

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

License

MIT