IAM Units

2026.3.10 verified Fri May 01 auth: no python

Unit definitions and conversion utilities for integrated-assessment modeling research. Version 2026.3.10 requires Python >=3.10 and is released frequently (monthly).

pip install iam-units

Common errors

error ModuleNotFoundError: No module named 'iam_units' ↓

cause Package name is 'iam-units' (hyphen), not 'iam_units' (underscore). This error occurs when trying to import before installation.

fix

Run pip install iam-units (hyphen). The import uses underscore: import iam_units.

error ValueError: Unit 'MtC' is not defined ↓

cause The unit 'MtC' was removed or renamed in v2026. The correct unit is 'Mt C' (with space) or 'Mt C_eq'.

fix

Use 'Mt C' (carbon mass) or 'Mt CO2_eq' (carbon dioxide equivalent) as appropriate.

Warnings

breaking Unit definitions for 'MtC' (megatonnes of carbon) changed between v2025 and v2026. Old definitions assumed carbon mass, new definitions use carbon-dioxide equivalent (CO2_eq). ↓

fix Review all calculations involving 'MtC' and update to explicit 'Mt C' or 'Mt CO2_eq'.

deprecated The module `iam_units.energy` is deprecated. Use `iam_units.emissions` with energy-related units. ↓

fix Replace `from iam_units.energy import ...` with `from iam_units import emissions`.

gotcha UnitConverter.convert returns a float, not a pint Quantity. Multiplication by 1.0 may lose precision. ↓

fix Use `uc.convert(..., return_quantity=True)` to get a pint Quantity object.

Imports

UnitConverter

wrong

from iam_units.converter import UnitConverter

correct

from iam_units import UnitConverter

The old public API was reorganized; use top-level import.

emissions
```
from iam_units import emissions
```
Standard import for emission unit definitions.

Quickstart

Basic conversion between common IAM units.

from iam_units import UnitConverter

uc = UnitConverter()
# Convert 1000 metric tons CO2 to CO2-equivalent in Gt
result = uc.convert(1000, 't CO2', 'Gt CO2_eq')
print(result)  # 1e-06 Gt CO2_eq