Installing Terraflux

Terraflux is one program, terraflux, that is both the application (a window) and the command line. Every package brings everything it needs: GDAL (the open-source library that reads and writes raster and vector files, with its data and PROJ's, which handle coordinate systems) and the runtime libraries of its compiled code. You do not need Python, R, or a GDAL of your own. This page gives the details of each package; the Quickstart has the short version.

Download the files from the download page. <version> below stands for the version number, such as 0.80.0.

Windows#

Windows 10 and 11, 64-bit.

Started by a double click, Terraflux opens the application without a console window. A model file dropped on terraflux.exe, or opened with it, opens in the application.

macOS#

Apple silicon (M1 or later).

The application brings GDAL (its libraries inside Terraflux.app/Contents/Frameworks/gdal, GDAL's and PROJ's data in Contents/Resources) and the OpenMP runtime. PROJ's large grids of datum shifts are left out to keep the download small.

Updates. As on Windows, Terraflux asks GitHub for a newer version when it starts (once a day; turn it off in the settings, ⚙), and Update to X.Y.Z appears in orange at the top. When Terraflux.app is in a folder you may write, it updates itself: it downloads the release's .zip, checks it against the release's checksums, unpacks it beside the application, then closes, puts the new Terraflux.app in the place of the old one and opens again with the model. If the application is in a folder you may not write, the window offers Open its page instead: download the new version from there and install it as the first time.

Linux#

x86-64 with glibc 2.39 or newer: Ubuntu 24.04 and later, Debian 13, Fedora 40 and later, and other distributions of 2024 or newer.

sudo apt install ./terraflux_<version>_amd64.deb

sudo dnf install ./terraflux-<version>-1.x86_64.rpm

sudo pacman -U terraflux-<version>-1-x86_64.pkg.tar.zst

tar xzf terraflux-<version>-linux-x64.tar.gz
cd terraflux-<version>-linux-x64
./install.sh

All of them bring GDAL (its library and every library it needs except the C and C++ runtimes, with GDAL's and PROJ's data and the web's certificates) and the OpenMP runtime. The application also needs your desktop's own graphics libraries: EGL or Vulkan, and X11's libxkbcommon-x11 or Wayland. A desktop installation has them; a minimal server or container does not (see below). The command line alone (terraflux run) needs none of them.

Updates. Terraflux tells of a newer version as on Windows (Update to X.Y.Z, in orange at the top), and how it updates itself depends on how it was installed:

• The archive (.tar.gz), in a folder you may write: the release's .tar.gz is downloaded, checked against the release's checksums and unpacked beside the folder; Terraflux closes, the new folder takes the place (and the name) of the old one, and Terraflux opens again with the model.
• The packages (.deb, .rpm, Arch's .pkg.tar.zst), in /opt/terraflux: the new package is downloaded and checked, Terraflux closes, and the system's package manager installs it (dpkg, rpm or pacman), asking for the administrator's password through pkexec; then Terraflux opens again with the model. This needs pkexec (part of polkit, which most desktop installations have) on the PATH.

Without these (a folder you may not write, no pkexec, Terraflux built from source), the window offers Open its page, to download the new version and install it by hand.

The command line#

Check that the command works:

$ terraflux --version
terraflux 0.80.0

terraflux with no command opens the application; terraflux app model.toml opens it with a model. The commands are described in the CLI reference, and terraflux help lists them:

Land use and land cover change modelling

Usage: terraflux [OPTIONS] [COMMAND]

Commands:
  app          Open the application (with a model, if given)
  run          Run a model and write its outputs
  check        Check a model and its data without running it
  reproduce    Run again what a run's manifest (manifest.json, written with its outputs) records: the same model, scenario, values and files (told when one changed), and tell whether every output is the same, byte for byte (vectors: the same features)
  test         Test models: run each (a folder: its models) and check what its [[tests]] say against the files of what they should be, and its check.assert nodes; `--update` writes those files from this run instead
  report       Write a model as a document: its data, preparation, model, validation and results, step by step, with the note, why and settings of each (an HTML page, or a PDF by the extension)
  plot         Run a model and write one of its Plots (`[[plots]]`, kept with the model) as a picture of its map: the layers at their opacity, the features with their style and labels, as the Viewer draws it (no legend or decorations)
  methods      Draft the methods section of a paper from a model: the methods it uses with the papers to cite, the model step by step and the references; or the references as BibTeX or RIS
  ops          List the operators (`--json`: their full signatures)
  new          Create a model from a classic land change model
  convert      Write a model in another format (by the extension: .toml or .json)
  mcp          A server of the Model Context Protocol on the standard input and output: an AI assistant (Claude, Gemini CLI, Codex...) builds, checks and runs models through it; the application, with the model open, shows its edits as they are made
  serve        Run a coordinator: workers ask it for tasks, clients submit batches to it
  worker       Run a headless worker: tasks from a coordinator, until stopped
  workers      The workers of a coordinator and what they do
  jobs         The jobs of a coordinator, done or not
  results      Follow a job of a coordinator to its end and write its files (those written already kept)
  submit       Run a batch of a model: replicates (one seed each) or scenarios, here or on a coordinator's workers
  calibrate    Calibrate settings of a model against an observed map, here or on a coordinator's workers
  sensitivity  A global sensitivity analysis of a model's output to its settings (Morris or Sobol, as SALib), here or on a coordinator's workers
  cluster      Clusters and servers reached by SSH: saved once, used by `submit --on`, `calibrate --on`, `results --on`
  cloud-init   The setup script (cloud-init user data) of a machine rented in the cloud: a server with Terraflux (then `terraflux cluster add`), or, with --worker, a machine working for a server's coordinator
  resample     Resample a raster to the grid of another (of the same coordinate reference system)
  help         Print this message or the help of the given subcommand(s)

Options:
      --threads <THREADS>  Threads to use (default and most: a quarter of the cores left free; never every core)
  -h, --help               Print help
  -V, --version            Print version

When something goes wrong#

The application does not start (Linux)#

Run terraflux app in a terminal to see the message. A missing libEGL, libvulkan or libxkbcommon-x11 means the desktop's graphics libraries are missing; on Ubuntu or Debian:

sudo apt install libegl1 libxkbcommon-x11-0

On a server without a screen, use the command line only: terraflux run, check and submit do not open a window. A message about GLIBC_2.39 means the distribution is older than the packages; use a newer one, or build Terraflux from source (see the README in the repository).

An update did not install#

When Terraflux opens again after an update and is still the old version, the top of the window says the update failed; its tooltip, and Updates in the settings, say Terraflux X.Y.Z was not installed (this is still ...); its log: .... The log is terraflux-update.log in the system's temporary folder: the installer's own log on Windows (%TEMP%\terraflux-update.log), the output of the script that replaced the application or ran the package manager on macOS and Linux. A wrong administrator's password, or the dialog of pkexec closed, ends there as not installed. Read it, then install the new version by hand from the download page.

The window stutters when it is moved or resized#

How frames reach the screen can be changed with environment variables, set before starting Terraflux:

For example, in PowerShell:

$env:WGPU_BACKEND = "gl"; terraflux app

and in a Linux or macOS terminal:

WGPU_BACKEND=vulkan terraflux app

WGPU_BACKEND=gl is also worth trying when the window opens black or does not open at all on an old graphics card or a remote desktop.

The computer is slow while a model runs#

Terraflux uses all the cores but one by default, so the computer stays usable. Use fewer with Settings > Threads in the application (from the next start), --threads 4 on any command, or the environment variable TERRAFLUX_THREADS.

A basemap does not appear#

Basemaps (satellite imagery and maps of the world under your data) are downloaded from their providers: they need an Internet connection, and a map with a coordinate system. See A tour of Terraflux.

A file does not open#

Terraflux reads every format its GDAL reads. A GeoTIFF that opens in QGIS opens in Terraflux; if one does not, check its path (paths in a model are relative to the model's folder) and open it alone with File > Open a raster or vectors... to see the message.

Where Terraflux keeps its things#

Removing these folders resets Terraflux to how it was installed.