Prerequisites

Installation

The recommended setup for development and reproducible workflows is an isolated Python environment (pixi, conda/mamba, venv, uv, etc.).

Warning

CryoSwath has a broad dependency tree. To avoid future dependency incompatibilities, install it in a dedicated environment.

Recommended: pixi-managed environment

git clone https://github.com/j-haacker/cryoswath.git
cd cryoswath
pixi install --locked -e test
pixi run -e test test-unit

For interactive work inside the environment:

pixi shell -e test

Alternative: install from source

git clone https://github.com/j-haacker/cryoswath.git
pip install --editable ./cryoswath

Then initialize your project directory:

mkdir <project_dir>
cd <project_dir>
cryoswath-init

cryoswath-init creates a project layout (data/, scripts/) and writes scripts/config.ini that stores your base data path.

Access requirements

Warning

Starting Monday, February 16, 2026, downloading CryoSat resources via CryoSwath requires an ESA EO account.

Set up your ESA credentials before running download workflows.

Anonymous FTP login is no longer supported.

Credential resolution order

CryoSwath resolves FTP credentials in this order:

1. ~/.netrc entry for science-pds.cryosat.esa.int with explicit login and password.

2. CRYOSWATH_FTP_USER and CRYOSWATH_FTP_PASSWORD.

3. Legacy config.ini values in [user] using name and password (temporary fallback).

Preferred setup (~/.netrc):

machine science-pds.cryosat.esa.int
  login your-esa-user
  password your-esa-password

Fallback setup (environment variables):

export CRYOSWATH_FTP_USER="your-esa-user"
export CRYOSWATH_FTP_PASSWORD="your-esa-password"

You can also write/update the ~/.netrc entry via:

cryoswath-update-netrc

Legacy config.ini [user] name/password credentials still work for now, but are deprecated and should be replaced.

Data dependencies

CryoSwath requires:

1. A reference DEM (currently ArcticDEM/REMA via cryoswath.misc.get_dem_reader()).

2. RGI v7 glacier/region geometries for most region-based workflows.

Expected default locations:

• DEMs: data/auxiliary/DEM

• RGI files: data/auxiliary/RGI

You can override paths in config.ini or by adapting path handling in cryoswath.misc.

Software dependencies

Python package dependencies are defined in pyproject.toml.

• Runtime dependencies: [project.dependencies]

• Optional docs/dev extras: [project.optional-dependencies]

• Supported Python version: >=3.11 (regularly tested on 3.11 and 3.12)

• Supported xarray window: >=2025.3,<2025.12

The root requirements.txt is kept for compatibility but is not the primary dependency source.

Dependency strategy

CryoSwath supports two installation modes:

1. Stable/reproducible: use pixi.lock or environment.yml.

2. Flexible: install from pyproject.toml bounds (pip/uv workflows).

Use the stable mode for tutorials, bug reports, and scientific reproducibility. Use the flexible mode when integrating CryoSwath into an existing environment.

Contributor lockfile workflow

For regular development runs:

pixi install --locked -e test

If you change dependency manifests (pyproject.toml and/or pixi.toml):

pixi lock
pixi run -e test test-unit
pixi run -e docs docs-build