Skip to content
VoLCA Docs

Start with Python

Task

Section titled “Task”

Run a standalone Python script that downloads a public BAFU database, starts a local VoLCA engine, selects one Swiss electricity activity, and prints a few inventory flows with their units.

Prerequisites

Section titled “Prerequisites”
  • Python 3.10 or newer and an internet connection for the first downloads.
  • A platform supported by the VoLCA release binaries.
  • A directory where you can create files. No account, hosted API subscription, or existing server is needed.

This exercise uses pyvolca 0.11.0 and VoLCA v0.12.0. pyvolca is a client library, not a bundled engine or database. The script explicitly calls its native download(), Server, and Client helpers to install and run the engine locally.

Action

Section titled “Action”

Create a fresh working directory, then a virtual environment:

Terminal window
mkdir volca-python-demo
cd volca-python-demo
python3 -m venv .venv
. .venv/bin/activate
python -m pip install pyvolca==0.11.0

On Windows, use py -m venv .venv and .venv\Scripts\Activate.ps1 in PowerShell instead of the activation command above.

Download first_result.py into this directory and inspect it before running it. On Linux or macOS:

Terminal window
curl -fL https://www.volca.run/onboarding/first_result.py -o first_result.py
python first_result.py

The script creates a dedicated volca-first-result subdirectory. It downloads BAFU 2026v1, verifies its SHA-256 even when reusing an existing archive, and creates a project-local volca.toml without overwriting a different configuration. It downloads the released engine and reference data, uses an automatically allocated local port, and stops its child server on exit.

The complete archive is 37,703,538 bytes. Its SHA-256 is:

5b5742de3bfe31a4cbeca6fe07e29c814e84c3fa5fec4d29fbb771042812664c

The core query is:

matches = client.search_activities(name="Electricity mix", geo="CH", exact=True)
if len(matches) != 1:
    raise RuntimeError(f"Expected one Swiss electricity mix, got {len(matches)}")
activity = matches[0]
inventory = client.get_inventory(activity.process_id)
for flow in inventory.flows[:5]:
    print(flow.quantity, flow.unit_name, flow.flow_name)

This excerpt runs inside the downloaded script’s managed-server context, not by itself. Request the inventory without limit, then slice the returned flows; the pinned released pair rejects get_inventory(..., limit=5).

Expected result

Section titled “Expected result”

The exact search selects Electricity mix, CH, reference 1 kWh, with process ID:

3dd9f4d2-ebc3-32d6-8138-ba4253c4ebc3_a99c8f9b-0339-5c79-a622-08e1b5bee775

The pinned database loads 11,947 activities. The inventory contains 2,147 flows: 1,795 emission flows and 352 resource flows. The script prints only five example rows, each with a unit. These are examples, not environmental hotspots. Do not sum mixed units or interpret the inventory as an LCIA result. No LCIA method archive is needed for this first exercise.

Troubleshooting

Section titled “Troubleshooting”
  • Checksum mismatch: remove only the named archive in the exercise folder and rerun. Do not bypass the check or silently trust a cached download.
  • Existing configuration differs: use a fresh working directory. The script deliberately refuses to overwrite your configuration.
  • Binary unavailable: check the supported release platforms. Package installation alone does not install the engine; the script’s download() performs that step.
  • No unique activity: check the archive checksum and selected database. The guard deliberately refuses to choose a first fuzzy result.
  • Need an existing server instead: use Client only with its real URL and credentials. Do not run Server or download a local engine for that mode.

Next step

Section titled “Next step”

Read the Python guide and API reference for typed records, supply chains, and impact calculations. For inventory interpretation, see supply chain and inventory concepts. To automate database production, see the production workflow.