Installing lsdtt3

The main option for installation of lsdtt3 is the pre-built release package which installs a series of command line interface programs: you run these in a Linux terminal (or a terminal on your operating system). This method is the way the developers primarily use this software, and is built for automated, repeatable analysis of large topographic datasets.

However, you can also use lsdtt3 in Google Colab, in our QGIS plugin, and using our Python package

For the pre-built release package you do not need a compiler, you do not need to install GDAL or any other library, and on Linux you do not need sudo — the package carries the command-line tools and every library they depend on.

Want the very latest code instead of a release? Then you need to compile it yourself. If you are not a developer you really do not want to do this. That activity is documented separately in Building lsdtt3 from source.

Where the packages live

Download everything from GitHub Releases. Every package is built and attached automatically when a release is made, and no account is needed. These links always fetch the newest release:

Package	Permanent link to the latest version
Linux	`lsdtt3-backend-linux-x86_64-core.tar.gz`
Windows (QGIS tool set)	`lsdtt3-backend-win64-qgis.zip`
macOS, Apple Silicon (QGIS tool set)	`lsdtt3-backend-macos-arm64-qgis.tar.gz`
macOS, Intel (QGIS tool set)	`lsdtt3-backend-macos-x86_64-qgis.tar.gz`
QGIS plugin	`lsdtt3-qgis-plugin.zip`
Python wheels	see Python package

These unversioned names exist from release 0.9.2 on. Each release also carries the same files with the version in the name, which is what to download for a particular older release (open it from the list of releases). The folder inside each archive is always named with its version.

A copy of some packages is also kept at https://www.geos.ed.ac.uk/~smudd/lsdtt_packages/. Use it only as a last resort, if GitHub is unreachable from your network: it is updated by hand and is usually several releases out of date.

Versioned file names look like this:

lsdtt3-backend-linux-x86_64-core-v0.7.1.tar.gz     Linux
lsdtt3-backend-win64-qgis-v0.7.1.zip               Windows (native, limited to the QGIS tool set)
lsdtt3-backend-macos-arm64-qgis-v0.7.1.tar.gz      macOS, Apple Silicon (QGIS tool set; from 0.9.1)
lsdtt3-backend-macos-x86_64-qgis-v0.7.1.tar.gz     macOS, Intel (QGIS tool set; from 0.9.1)
lsdtt3-qgis-plugin-0.7.1.zip                       QGIS plugin (shares the number from 0.7.0)

core and qgis are profiles — which set of command-line tools the package contains. core is the general-purpose set; qgis is the smaller subset the QGIS plugin drives. Native Windows and macOS packages are qgis only: for the full tool set on those systems, run the Linux package under WSL2 or in a Linux VM.

lsdtt3 has one version number for everything: the command-line tools, the backend packages, the QGIS plugin and the Python package. Files from the same release go together.

You do not need to know the version number to install. The links and commands on this page fetch the latest release and match the versioned folder inside it with *. A version number that appears below is an example of a versioned name. To see which version you have, look at the folder name, or run any tool with -v.

Choose your route

1. Where do you want to run lsdtt3?


On my own computer	continue to question 2
In a browser, with nothing installed	Google Colab
Inside QGIS	QGIS plugin (plus a backend package from question 2)
From Python scripts	Python package

2. What is your computer running?


Linux	Linux package
Windows	Windows, via WSL2 — recommended, full functionality
Windows, and I want native `.exe` files	Windows native package — reduced tool set
macOS	macOS

Linux package

This is the main way to install, and in other operating systems you just end up emulating Linux, so it works for all the pathways.

1. Download and unpack

wget https://github.com/LSDtopotools/lsdtt3/releases/latest/download/lsdtt3-backend-linux-x86_64-core.tar.gz
tar -xzf lsdtt3-backend-linux-x86_64-core.tar.gz
ls -d lsdtt3-backend-linux-x86_64-core-v*      # the folder name shows the version

2. Activate it

source lsdtt3-backend-linux-x86_64-core-v*/setenv.sh

(If you have unpacked more than one version in the same place, give the full folder name instead of the *.)

setenv.sh must be sourced, not run with bash. All it does is export environment variables (PATH, LD_LIBRARY_PATH, GDAL_DATA, PROJ_DATA), and those vanish with the child process if you execute it instead.

3. Check it worked

lsdtt-channel-extraction --help

A list of parameters means you are done.

4. Make it permanent (optional)

setenv.sh applies to the current terminal only. To have the tools available in every new terminal, append the same line, with the full path, to the end of your ~/.bashrc:

# run this in the folder where you unpacked it; it writes the full path
echo "source $(cd lsdtt3-backend-linux-x86_64-core-v* && pwd)/setenv.sh" >> ~/.bashrc

After installing a newer release, edit that line in ~/.bashrc to point at the new folder.

What you need

Very little: a 64-bit x86 Linux system. The package is built on Ubuntu 22.04, which sets the oldest glibc it will run against — anything that age or newer works. It does not bundle glibc itself, so a distribution older than Ubuntu 22.04 may refuse to start it.

Debian package (experimental, untested)

The repository also contains a Debian package definition under debian/, which builds a .deb linking the system GDAL, PROJ, FFTW and netCDF through Depends: rather than bundling them. That keeps the package small and lets it track your distribution's security updates, which is the opposite trade-off from the tarball above.

This route is not tested

The .deb build has not been through the testing the tarball packages have, and no .deb is published. It is included because the definition exists and works for the developers, not because it is ready to rely on. Use the tarball above unless you specifically want the system-library build and are prepared to debug it. If you try it and something breaks, a bug report is genuinely useful.

Building it is a developer task rather than an install step — the procedure, the dependency list and the smoke test are in debian_packaging.md.

Windows, via WSL2

lsdtt3 runs best on Windows through WSL2 (Windows Subsystem for Linux), which gives you a real Ubuntu terminal inside Windows. You then use the Linux package exactly as above.

This is the recommended Windows route: you get every tool, and in our testing the Linux build running under WSL2 is faster than a native Windows build on the same machine. We don't understand how that can be the case but friends, strange things happen.

1. Install WSL2 and Ubuntu

Open PowerShell as administrator (right-click the Start menu → Terminal (Admin)). You may need to become friendly with your IT team to be able to do this.
Run wsl --install.
Restart when prompted.
Open the Microsoft Store, search for Ubuntu 22.04 LTS, install it.
Launch Ubuntu from the Start menu. The first launch asks you to create a username and password (don't forget your password!) the password is what sudo will ask for later.

2. Install the Linux package

Follow Linux package inside the Ubuntu terminal.

If you downloaded the tarball with a Windows browser it is on your Windows disk, which WSL2 mounts under /mnt/. A file at C:\Users\Alice\Downloads\lsdtt3-backend-linux-x86_64-core.tar.gz is:

/mnt/c/Users/Alice/Downloads/lsdtt3-backend-linux-x86_64-core.tar.gz

You will need to update this path unless your username is Alice.

3. Working with your Windows files

The same /mnt/ mapping lets the tools read and write DEMs that live on your Windows drives, so you can keep your data where your GIS expects it:

lsdtt-raster-preprocessing /mnt/c/Users/Alice/data/ my_analysis.driver

Note that reading and writing across /mnt/c is noticeably slower than working inside the Linux filesystem (~/). For large DEMs, copy the data into your Linux home directory first.

(The developers of lsdtt3 try to avoid using a GIS since it takes forever to start, so they use lsdviztools3 instead).

WSL2 troubleshooting

No internet inside Ubuntu (downloads fail, apt cannot reach anything). Set the DNS server manually:

sudo nano /etc/resolv.conf

Make the file contain exactly:

nameserver 8.8.8.8

Save with Ctrl-O, exit with Ctrl-X. If the file reverts after a reboot, also create /etc/wsl.conf containing:

[network]
generateResolvConf = false

Windows native package

A native Windows build exists, distributed as a .zip. It is a reduced build and exists mainly as the backend for the QGIS plugin:

it ships the qgis profile, not the full tool set;
Eigen-dependent routines are disabled, so some analyses are missing or skip their optional steps;
it is generally slower than the same machine running the Linux package under WSL2.

Unless you specifically need .exe files — for the QGIS plugin, or because WSL2 is unavailable on a managed machine — use WSL2.

Download lsdtt3-backend-win64-qgis.zip (always the latest release) and unzip it (right-click, Extract All…). Then in PowerShell, in the folder you extracted to:

cd lsdtt3-backend-win64-qgis-v*
. .\setenv.ps1
.\bin\lsdtt-raster-preprocessing.exe --version

Note the leading . (dot, space) — like source on Linux, it runs setenv.ps1 in your current shell so the environment it sets survives.

macOS

There are three ways to run lsdtt3 on a Mac. Choose by what you need:

You want	Use
The QGIS plugin	The native macOS package
lsdtt3 from Python	The Python package, which runs natively
Every command-line tool	The Linux package in a virtual machine

Native macOS package (QGIS tool set)

A native package is built for every release from 0.9.1, for Apple Silicon (M1 and later) and Intel Macs, and needs macOS 15 or later. It is a reduced build: it ships the qgis profile, the tools the QGIS plugin drives, not the full tool set. It is new, so please report any problem with it.

Download the package for your Mac (these links always fetch the latest release): Apple Silicon or Intel. Apple menu → About This Mac shows which you have: an "Apple M…" chip is Apple Silicon.
Open Terminal in the folder you downloaded it to (in Finder, right-click the folder, then New Terminal at Folder) and unpack it:

tar -xzf lsdtt3-backend-macos-arm64-qgis.tar.gz

Clear the quarantine flag the browser put on the download. Without this, macOS blocks the tools because they are not from the App Store:

xattr -dr com.apple.quarantine lsdtt3-backend-macos-arm64-qgis-v*

Activate the tools for this Terminal window, and check they run:

source lsdtt3-backend-macos-arm64-qgis-v*/setenv.sh
lsdtt-raster-preprocessing --version

Use source, not bash: running the script in a new shell does not set up the current one. Repeat it in each new Terminal window, or add the source line, with the full path, to your ~/.zshrc.

For Intel Macs, use x86_64 in place of arm64 in these names. The package's own README.md repeats these steps. To use it with QGIS, select the unpacked folder in the plugin's settings; see QGIS plugin. For the tools the package does not include, use the VM below.

The full tool set in a Linux VM

For every command-line tool, run the Linux package inside a lightweight Ubuntu virtual machine using Multipass, which Canonical maintain for exactly this.

brew install --cask multipass
multipass launch --name lsdtt --cpus 4 --memory 8G --disk 40G 22.04
multipass shell lsdtt

You are now at an Ubuntu 22.04 prompt — follow Linux package from there.

To share a macOS folder into the VM so the tools can reach your data:

multipass mount ~/topographic_data lsdtt:/home/ubuntu/data

Stop and restart the VM later with multipass stop lsdtt / multipass start lsdtt.

Google Colab

Colab already runs Linux, so the Linux package works there with nothing installed on your own machine at all. Two things differ from a normal terminal.

Download and unpack the latest release in a code cell (! runs a shell command):

!wget -q https://github.com/LSDtopotools/lsdtt3/releases/latest/download/lsdtt3-backend-linux-x86_64-core.tar.gz
!tar -xzf lsdtt3-backend-linux-x86_64-core.tar.gz

Do not use !source setenv.sh. Every ! line runs in its own throwaway shell, so nothing it sets survives to the next cell. Set the environment from Python instead, once per session:

import glob, os

root = sorted(glob.glob("/content/lsdtt3-backend-linux-x86_64-core-v*"))[-1]
print("Using", root)
os.environ["PATH"] = f"{root}/bin:" + os.environ["PATH"]
os.environ["LD_LIBRARY_PATH"] = f"{root}/lib:" + os.environ.get("LD_LIBRARY_PATH", "")
os.environ["GDAL_DATA"] = f"{root}/share/gdal"
os.environ["PROJ_DATA"] = f"{root}/share/proj"
os.environ["PROJ_LIB"]  = os.environ["PROJ_DATA"]

After that cell the tools work anywhere in the notebook:

!lsdtt-channel-extraction --help

Remember that Colab sessions are wiped when they end — you will repeat both cells next time, and anything you want to keep must be copied to Google Drive.

QGIS plugin

The plugin adds an lsdtt3 group to the QGIS Processing Toolbox. It runs the command-line tools, so it needs a backend package as well:

Install a backend package for your system: the Windows native package on Windows, the Linux package on Linux, or the macOS qgis package (Apple Silicon or Intel) on macOS. The macOS package's README.md covers unpacking it and clearing the browser's quarantine flag.
Download the plugin from the same release: lsdtt3-qgis-plugin.zip is always the latest. Download it from GitHub, not from any other copy you come across: an older plugin may refuse a newer backend.
In QGIS: Plugins → Manage and Install Plugins… → Install from ZIP, and choose the zip.
Open lsdtt3 → LSDTT Backend Settings and select the backend package's root folder (the one containing bin/, share/ and manifest.json).

The plugin and the backend must come from the same X.Y series: plugin 0.7.x works with any 0.7.x backend. A mismatch is refused before anything runs, with a message saying whether to update the plugin or the backend. Plugins up to 0.4.0 predate this rule; if one reports that the backend "supports plugin versions …", update the plugin.

To update either, repeat its install step: Install from ZIP replaces the plugin in place, and a new backend goes in a new folder, which you then select in the settings.

Python package

The lsdtt3 Python package wraps the same C++ code for use from scripts and notebooks, keeping rasters and results in memory instead of files. It shares the lsdtt3 version number, and is built for Linux, macOS and Windows on every release.

Install it from PyPI, into a virtual, conda or pixi environment rather than your system Python:

python -m pip install lsdtt3

It needs Python 3.12 or later, on Linux (x86_64), macOS (Apple Silicon and Intel, macOS 15 or later) or Windows (x64). There is one wheel per platform, cp312-abi3: built against Python's stable ABI, the same file installs on 3.12, 3.13, 3.14 and later.

In Google Colab, run this in a code cell:

!pip install lsdtt3

From a GitHub release. The same wheels are attached to each GitHub release, as are the wheels of versions up to 0.9.3, which are not on PyPI (those have a separate wheel for each Python version, cp310 to cp314). pip reads the Python and platform from the file name, so keep the name as it is. This command, run with the Python you will use, prints the address of the matching wheel in the latest release:

python - <<'EOF'
import json, platform, sys, urllib.request
if sys.version_info < (3, 12):
    sys.exit("lsdtt3 needs Python 3.12 or later")
rel = json.load(urllib.request.urlopen(
    "https://api.github.com/repos/LSDtopotools/lsdtt3/releases/latest"))
plat = {"linux": "manylinux", "darwin": "macosx", "win32": "win_"}[sys.platform]
arch = platform.machine().lower()      # x86_64, arm64 or amd64
for a in rel["assets"]:
    n = a["name"]
    if n.endswith(".whl") and "-abi3-" in n and plat in n and arch in n.lower():
        print(a["browser_download_url"])
EOF

Then install from that address:

python -m pip install https://github.com/LSDtopotools/lsdtt3/releases/download/vX.Y.Z/lsdtt3-X.Y.Z-cp312-abi3-manylinux_2_28_x86_64.whl

If it prints nothing, that release has no wheel for your platform, or your Python is older than 3.12; the list of releases shows which wheels each one has.

You do not need the backend tarball or the os.environ cell from Google Colab for the Python package; the wheel finds its own GDAL and PROJ data.

The wheel is self-contained: it bundles GDAL and PROJ, and also installs the command-line tools as commands. Install it into a virtual environment, conda or pixi environment, not into your system Python. Check what you have with:

python -c "import lsdtt3; print(lsdtt3.__version__, lsdtt3._core.lsdtt3_version())"

To use the Python package from unreleased code, build it from a clone; see Building the Python wheels. The Python guide shows what to do once it is installed. Every function is documented in the package itself (help(lsdtt3.FlowInfo)), and print(lsdtt3.helper_for_llm("all")) prints a compact guide written for you or for an AI assistant such as Gemini in Colab.

What is inside a package

Path	Contents
`bin/`	the `lsdtt-*` command-line tools
`lib/`	every shared library they need (GDAL, PROJ, …)
`share/gdal`, `share/proj`	support data those libraries read at runtime
`share/lsdtt3`	lsdtt3's own data (the cosmogenic-nuclide parameter file)
`setenv.sh` / `setenv.ps1`	sets `PATH` and the library/data variables
`manifest.json`	version and a SHA256 checksum of every file
`README.md`	the same instructions, offline
`LICENSE`, `THIRD_PARTY_NOTICES.txt`	the AGPL licence, and the licences of the bundled libraries

Nothing is installed system-wide. To uninstall, delete the folder (and the source line from ~/.bashrc if you added one).

Troubleshooting

command not found after sourcing setenv.sh Check the bundle's bin is on your PATH:

echo $PATH | tr ':' '\n' | grep lsdtt3

If nothing prints, you probably ran setenv.sh instead of source-ing it, or you are in a different terminal from the one where you sourced it.

error while loading shared libraries The lib/ folder is not being found. This happens if you moved or renamed the bundle directory after sourcing setenv.sh — re-source it from its new location.

version 'GLIBC_2.35' not found Your Linux distribution is older than the Ubuntu 22.04 the package was built against. Use a newer distribution, or build from source.

If you already have GDAL or PROJ installed

This is the most common source of confusing behaviour, and it gets more likely the more serious your GIS setup is. If you have QGIS, conda, rasterio, geopandas or a system libgdal — and anyone doing large-scale analysis does — then there is more than one GDAL and more than one PROJ on your machine.

The good news: lsdtt3 pins its own data directories at startup. A proj.db bundled next to the binary always wins over PROJ_DATA, PROJ_LIB or GDAL_DATA in your environment. You do not have to unset anything, and you do not have to source setenv.sh for the tools to find their own data — that matters in places like Google Colab where each ! line is a separate shell.

Check what is actually in use with any tool's -v (shown here as 0.7.0 and later print it; the first line names the lsdtt3 version and whether the tool is stable or experimental):

lsdtt-raster-preprocessing -v

lsdtt-raster-preprocessing (lsdtt3 0.7.1, stable)
GDAL 3.8.4, PROJ 9.3.1
  proj data: bundled: /home/you/lsdtt3/share/proj
  GDAL data: bundled: /home/you/lsdtt3/share/gdal

bundled: means lsdtt3 is using its own copy and your environment is being ignored, which is what you want from a package. If it says PROJ_DATA=… or PROJ built-in search instead, it is using something else — expected for a source build or a conda install, worth knowing about for a package.

Why we care so much about this. A mismatched proj.db does not usually produce an error. It produces coordinates. They will be the right shape, in the right part of the world, and wrong by tens of metres, because the datum transformation your CRS needs was resolved differently or not at all. That is much worse than a crash, and it is why the version banner reports the data directories at all.

Please include the whole -v output in any bug report that involves projections, reprojection, or coordinates that look subtly off. It is the first thing we will ask for.

Symptoms that point here:

What you see	What it usually means
`Cannot find proj.db`	`PROJ_DATA` or `PROJ_LIB` points somewhere without one, and nothing is bundled
`Cannot find proj.db` from a conda environment	conda's PROJ and a system PROJ disagree; activate the environment, or use a release package instead
Coordinates off by ~100 m in a national grid	a datum shift was not applied — a wrong `proj.db`, not a bug in the analysis
`undefined symbol: GDAL…` when building	headers from one GDAL, library from another — see the build-from-source notes
GeoPackage writes fail under WSL2 on `/mnt/c`	SQLite on an NTFS mount; write FlatGeobuf instead

Reporting bugs

This is software built by academics for academic use within a research group. It is not supported commercial software. The developers are happy to help with questions, comments and bug reports, but they may be teaching or doing research, or sitting in administrative meetings, or filling in tedious paperwork, or reviewing your grant or paper. Please adjust expectations of response times accordingly.

Please include:

The exact command you ran.
The full terminal output — copied and pasted as text, not a screenshot.
Your Linux version: cat /etc/os-release | grep VERSION=
The lsdtt3 version: lsdtt-channel-extraction -v

Open an issue on the GitHub repository if you have access, or send it to the developers.