HESTIA Converters

Library to convert from/to the HESTIA format.

Install

Install one converter, not all of them. Each converter is its own install extra, named in the Converters table below, and installing it is the whole install — the extra brings the base library and the hestia-convert command with it:

pip install "hestia-earth-converters[SimaPro]"

Several converters go in one pair of brackets, comma-separated:

pip install "hestia-earth-converters[Klim,LSRS]"

Keep the quotes. zsh reads an unquoted [SimaPro] as a glob and refuses the command with no matches found; bash happens to pass it through, so quoting is what works in both.

Add a format later by running the same command again with the new extra. Nothing else needs redoing: the next conversion notices the new converter and downloads the flowmap bundles it needs.

A conversion that needs an extra you do not have stops before it reads anything, and names the command that fixes it — hestia-convert --help lists every format the package ships, not the subset you installed:

Please install 'hestia-earth-converters[OpenLCA]' first (No module named 'olca_schema').

A chained conversion needs the extra at each end. Klim -> LSRS runs Klim -> HESTIA and then HESTIA -> LSRS, so it wants [Klim,LSRS]; both are checked before the first leg writes a file.

Some data needs an API key, as does downloading any node with --hestia-impact-id. Create an account, copy the key from the "API Access" section of https://www.hestia.earth/profile, and set it as the API_ACCESS_TOKEN environment variable.

Working on the converters themselves rather than using them? CONTRIBUTING.md sets up a source checkout.

Quick start

# a HESTIA ImpactAssessment, downloaded by id, as a SimaPro CSV
hestia-convert --output-folder out --input-format HESTIA --output-format SimaPro \
  --hestia-impact-id cocoaSeedWhole-ghana-2010-2025-20250916

# a file on disk, converted to HESTIA nodes
hestia-convert --output-folder out --input-format OpenLCA --output-format HESTIA \
  --input-file export.zip

Where no converter goes straight from one format to another, the CLI runs the pair that does, by way of HESTIA. So every input format reaches LSRS:

hestia-convert --output-folder out --input-format Klim --output-format LSRS \
  --input-file farm.zip

runs Klim -> HESTIA, then HESTIA -> LSRS over what it wrote. The intermediate HESTIA files stay in --output-folder — they are output too, and they are what makes a chained run debuggable. --filter-by-name names a result of the first leg, and the rest of the chain sees only what it selected.

These flags apply to every conversion. Each converter adds more of its own, prefixed with its name; its README lists them.

Converters

The extra in the third column is what goes in the brackets of pip install "hestia-earth-converters[...]"; each converter's page opens with its own install command.

Term mappings come from hestia-convert-flowmaps, downloaded automatically unless --mapping-files-directory points elsewhere. Errors and omissions in a mapping belong in an issue on that repository.

A run that had to drop a flow says so, and leaves you the list. What the flowmaps do not cover is written to missing-flowmaps.txt — one line per flow, deduplicated, with the name and unit the source states for it — and the run ends by naming that file and the issue tracker to attach it to. Nothing is written when everything mapped. --missing-flowmaps-file puts it somewhere else.

# 8 flow(s) this conversion could not map, and so dropped.
# conversion: FCC -> HESTIA
# flowmaps: 20260821-8550eee8
...
# direction	nomenclature	flow	name	unit
to HESTIA	FCC	proc_00141	On-farm processing (i.e. veg boxes) - Water ... - Mains water ...	m3

The file is a record of one run against one version of the flowmaps, so it is gitignored rather than committed.

Every run checks whether a newer version has been published and warns if so, naming the version in use and the current one. It does not download it: a flowmap version is part of what produced a result, so the same command keeps giving the same answer until you say otherwise. Pass --update-flowmaps to take the new version instead.

The check reads a single 18-byte file and is advisory only — if it cannot be reached, the conversion runs on what is already on disk. Only the default hestia-flowmaps folder is checked; a folder you name is yours, whether it is edited or deliberately pinned. The version in use is recorded in hestia-flowmaps/version.txt, so a folder assembled before that file existed reports as unrecorded until it is next downloaded.

Only the bundles your install needs are downloaded. The flowmaps are published per nomenclature, and each bundle belongs to an install extra — someone who installed [FCC] gets the four FCC maps rather than all 101, which is 40KB instead of 22MB compressed. The whole archive is still what you get when the extras cannot be worked out, such as a source checkout with nothing installed. To choose the set yourself:

python download_flowmaps.py --bundle fcc klim --version-filepath tests/flowmaps-version.txt

Bundles unpack into the same folder, so several combine. An unknown name is refused before anything downloads, and the published names are listed in the error.

Or say what to leave out, which is what CI does — a set stated this way needs no edit when a converter is added, because its bundle is included the moment the pinned version carries it:

python download_flowmaps.py --exclude-bundle other --version-filepath tests/flowmaps-version.txt

other is the one nothing loads: it unpacks into FlowMaps/other_flowmaps/, and get_all_flowmapping() iterates FlowMaps/ non-recursively. It is also 143MB of the 185MB archive, so excluding it alone is most of the saving.

A download that fails costs nothing. The new copy is built in hestia-flowmaps.download and swaps in only once it is complete, so the folder a conversion reads is either the previous version or the whole new one — never the remains of a download that died half way. The same is true of --update-flowmaps: if it cannot fetch the new version, the conversion runs on the copy already on disk and warns which version that is.

--require-converter-bundles fails a download that left a converter without flowmaps, naming the bundle and the files. Worth it because the absence is otherwise silent: a conversion with no maps does not fail, it writes a document stripped of every mapped node. Which bundles count is the published list's own answer — each one names the install extra it belongs to — so a converter added later is covered without being named here, and one that reads no flowmaps is never asked for.

Adding a converter? See CONVERTER_BLUEPRINT.md. Contributing? See CONTRIBUTING.md.