Installation¶

Prerequisites¶

Python >= 3.11
uv — fast Python package and project manager
Sufficient disk space for downloaded datasets (varies by region and time range)
API credentials for the data providers you intend to use

Install from PyPI¶

pip install h2mare
# or
uv add h2mare

Install from source¶

git clone https://github.com/h2ugoparra/h2mare.git
cd h2mare
uv sync

Include development dependencies (pytest, ruff):

uv sync --dev

Verify installation¶

h2mare --help

Expected output lists the available commands: run, compile, convert, catalog

First-time setup¶

H2MARE requires two files in your working directory before running any command.

`config.yaml`¶

Defines variables, dataset IDs, bounding boxes, and processing parameters. Download the template from the repository and edit it to match your setup:

curl -O https://raw.githubusercontent.com/h2ugoparra/h2mare/main/config.yaml

`.env`¶

Create a .env file with at minimum:

STORE_ROOT=/path/to/your/storage

See Configuration for the full list of variables and credentials.

Where to place these files¶

By default, h2mare searches for config.yaml by walking up from your current working directory. As long as you run h2mare from inside your project tree, no extra configuration is needed.

If auto-detection fails — for example, you run h2mare from an unrelated directory, or a script elsewhere imports h2mare — set H2MARE_ROOT to the directory containing your config.yaml and .env:

H2MARE_ROOT=/path/to/your/h2mare/project

Without it, h2mare falls back to ~/.h2mare (library mode), where no data directories are created and commands will fail.

Data storage layout¶

$PROJECT_ROOT/
├── data/raw/
│   └── downloads/<local_folder>/    # raw NetCDF / GRIB files from downloaders
├── data/interim/                    # temporary scratch files (checkpoints, tmp Zarr)
├── data/processed/
│   ├── zarr/<local_folder>/         # per-variable Zarr stores (fallback when STORE_ROOT is not set)
│   ├── parquet/                     # Hive-partitioned Parquet store
│   └── metadata/                    # ZarrCatalog Parquet indices
└── logs/                            # pipeline log files

$STORE_ROOT/<local_folder>/          # per-variable Zarr stores (when STORE_ROOT is set)

local_folder is defined per variable in config.yaml (e.g. CMEMS_SST, CMEMS_SSH). When STORE_ROOT is set, Zarr output goes there; otherwise it falls back to data/processed/zarr/.