Installation

This page covers installing the zephyr Python package itself — for running extractions directly, without going through the web interface. If you just want to request data, see Using the Web Interface instead.

Note

Zephyr reads NetCDF files from /net/atmos/data, which is only reachable from IAC’s internal network. Installing zephyr on your own laptop works fine for development and running the test suite, but a real extraction needs to run on an IAC machine (e.g. co2.ethz.ch, or any other IAC Linux server/workstation with /net/atmos/data mounted).

Requirements

  • Python >= 3.10

  • uv — used to create the virtual environment and install pinned dependencies from uv.lock

Installing on an IAC machine (e.g. co2)

  1. SSH into an IAC machine that has /net/atmos/data mounted:

    ssh co2.ethz.ch

  2. If uv isn’t already installed for your account, install it once (no root required):

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Clone the repository and run the setup script:

    git clone git@github.com:C2SM/zephyr.git
cd zephyr
./tools/setup.sh

    This creates a .venv and installs zephyr together with its test dependencies, pinned via uv.lock. It also registers a Jupyter kernel named zephyr, useful if you want to explore extraction results interactively on a IAC JupyterHub.

  4. Activate the environment:

    source .venv/bin/activate

From here, jump to Running an Extraction to process a request.

Tip

Steps 1-4 are identical on any IAC machine — there’s nothing co2-specific in the setup itself, only that the machine you pick needs /net/atmos/data mounted (true for co2 and most other IAC login/compute nodes).

Installing locally (development, tests that don’t need /net/atmos/data)

The same steps work on a laptop or any machine outside the IAC network:

git clone git@github.com:C2SM/zephyr.git
cd zephyr
./tools/setup.sh
source .venv/bin/activate

Alternatively, install just the runtime dependencies directly with uv sync (add --extra test or --extra docs as needed).

Warning

Outside the IAC network, tests/requests (which reads real files from /net/atmos/data) will fail — see Development for how the test suite is split up.

Updating

Pull the latest changes and re-run uv sync (via ./tools/setup.sh, or directly) any time pyproject.toml or uv.lock changes:

git pull
uv sync --extra test