Skip to content

Installation

IGM requires Python 3.10–3.12. GPU acceleration requires an NVIDIA card; CPU-only runs are slower but fully supported.

Coming from IGM v2?

This documentation covers IGM v3. For IGM v2, visit the former documentation or the v2 → v3 migration guide.

Upgrading from IGM v3.1?

See the v3.1 → v3.2 migration guide for the breaking changes between those releases.

Prerequisites

Select your operating system:

Check that your NVIDIA driver is installed and up to date:

nvidia-smi

If the command is not found or the driver is outdated, see NVIDIA Drivers.

  • CPU: works out of the box — no driver or source changes needed.
  • M-series GPU (Metal): supported, but requires installing from source (see Install below). Only tested on M4.

TensorFlow does not support GPU execution natively on Windows, and oggm_shop does not work on Windows. Install WSL2 (Ubuntu) first — it provides a Linux terminal and inherits your host NVIDIA drivers automatically.

wsl --install Ubuntu-22.04
sudo apt update && sudo apt upgrade

See WSL2 setup for a detailed walkthrough. Once inside WSL, follow the Linux instructions above.

Virtual environment

conda create -n igm python=3.11
conda activate igm

python3.11 -m venv igm
source igm/bin/activate

See Virtual Environments for a more detailed walkthrough.

Install

Disk space

A fresh install takes about 5.5 GB, mostly TensorFlow and its bundled CUDA libraries. Plan for ~10 GB free during installation (pip cache, reclaimable with pip cache purge).

pip install igm-model

To pin a specific release for reproducibility:

pip install "igm-model==3.2.1"

All available releases are listed on PyPI.

For the latest development version or to contribute to IGM:

git clone https://github.com/instructed-glacier-model/igm.git
cd igm
pip install -e .

The -e flag installs IGM in editable mode: changes to the source are reflected immediately without reinstalling.

Warning

The source version may be unstable between releases. For production use, prefer pip install igm-model.

Clone the repository and make two manual edits before installing.

git clone https://github.com/instructed-glacier-model/igm.git
cd igm

1. Edit setup.py — replace the TensorFlow lines:

# Remove:
"tensorflow[and-cuda]==2.17.0",

# Add:
"tensorflow==2.17.0",
"tensorflow-metal",

2. Disable JIT compilation — tensorflow-metal does not support JIT compilation. Replace every occurrence of jit_compile=True with jit_compile=False, and of set_jit(True) with set_jit(False), throughout the source:

grep -rl "jit_compile=True" . | xargs sed -i '' 's/jit_compile=True/jit_compile=False/g'
grep -rl "set_jit(True)" . | xargs sed -i '' 's/set_jit(True)/set_jit(False)/g'

3. Install:

pip install -e .

Note

This procedure has been tested on M4. We plan to streamline macOS installation in a future release.

Verify

igm_run --help

A successful installation prints the IGM help text. You are ready to run your first simulation.