2. Installation

Precompiled binaries are available for the stable releases and the current development build. Conda packages exist for the stable versions (Section 2.2).

2.1. Precompiled binaries

2.1.1. Linux

Binaries are available for both Intel (x86_64) and ARM64 (aarch64) architectures.

Choose either the latest build (recommended) or a stable release from:

No installation steps or administrative rights are necessary. Extract the archive, and run the executables in the bin subdirectory as:

tar xvf StereoPipeline-3.7.0-2026-06-07-x86_64-Linux.tar.bz2
./StereoPipeline-3.7.0-2026-06-07-x86_64-Linux/bin/stereo --help

Adjust the tarball name for your OS and architecture (Intel or Arm). The result of the last command should be a help message.

To permanently add the ASP executable subdirectory to your PATH, add to your shell configuration (e.g., ~/.bashrc), a line similar to:

export PATH="${PATH}":"/path/to/StereoPipeline/bin"

Then, run source ~/.bashrc (or open a new terminal) for the changes to take effect.

The latest additions are documented in Section 24.

See note on custom-built packages for ASP 3.7.0 in Section 2.2.

2.1.2. MacOS

ASP is available for the Mac Intel and Mac Arm architectures. The installation steps are the same as for Linux. It is important to note that:

  • An error may be shown about not being able to verify the developers. That can be overridden in the Privacy & Security settings of the system. Consider using instead the conda-based installation (Section 2.2), which should not have this issue.

  • Running the Intel build the first time will be slow, as Rosetta will translate the instructions to the native architecture. Subsequent runs will be faster.

2.1.3. Windows

ASP does not offer Windows binaries. However, the Linux build can be run on Windows using the Windows Subsystem for Linux (WSL). Use the x86_64 build for Intel/AMD processors and the ARM64 build for ARM-based Windows devices. Once a recent Linux distribution is installed and verified to work, the installation steps are the same as for Linux.

2.2. Conda-based installation

The ASP 3.7.0 release (June 2026) can be installed via conda, together with ISIS 10.0.0 (Section 2.3.1) for Linux Intel, Linux Arm, Mac Intel, and Mac Arm.

This ASP release ships with custom-built conda packages of ISIS (isis=10.0.0=asp*), and also for ALE, USGSCSM, and SpiceQL, hosted on the nasa-ames-stereo-pipeline channel. These provide fixes for bugs that are not yet part of the official releases of those packages. These are based on the latest dev source as of 2026-06-04. The asp build string distinguishes them from the official USGS and conda-forge releases.

To install conda, see:

Make the fetched installation file executable and run it, such as:

chmod u+x ./Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh

on Linux, and analogously on OSX. Use the suggested:

$HOME/miniconda3

directory for installation.

Configure the conda channels:

conda config --env --add channels conda-forge
conda config --env --add channels usgs-astrogeology
conda config --env --add channels nasa-ames-stereo-pipeline

Do not skip doing each of these three, even if you think you already have some of these channels.

Run:

conda config --show channels

to ensure that the order of channels is:

- nasa-ames-stereo-pipeline
- usgs-astrogeology
- conda-forge

Not having the channels in this order is likely to result in failure to install ASP. Do not use the defaults channel.

Install ASP with the commands:

conda config --set channel_priority flexible
conda create -n asp            \
  -c nasa-ames-stereo-pipeline \
  -c usgs-astrogeology         \
  -c conda-forge               \
  stereo-pipeline=3.7.0

This will create a new environment named asp and install ASP 3.7.0 together with custom-built ISIS 10.0.0 and all other dependencies.

The priority setting is set to flexible, as otherwise conda can get confused if the same package (even with old versions) exists in more than one channel.

Note that the latest build (Section 2.1) may have more features and fixes than this official release.

2.2.1. Environment setup

Run:

conda activate asp

and set:

export ISISROOT=$CONDA_PREFIX

in any new shell. Activating the environment puts the ASP binaries in the path and initializes several environment variables, such as PROJ_DATA and GDAL_DATA. It does not set ISISROOT, so the export above is required. The ISIS-based tools fail without it.

Check if the stereo command is found by running:

which stereo

When working with planetary images with ISIS, the ISISDATA environmental variable also needs to be set (Section 2.3.1). For more information see the ISIS installation instructions.

2.2.2. Alternative approaches

Consider using mamba instead of conda for the installation, as it is much faster. (Note that recent conda distributions default to using the mamba solver.)

ASP can be installed with Docker (instructions).

ASP can be built from source (Section 26).

2.3. Post-installation

The next steps depend on whether it is desired to process planetary (non-Earth), Earth, or aerial images.

2.3.1. Planetary images

To process images from NASA’s spacecraft that are exploring other planets, install ISIS and its data. Summary of the steps:

  1. Fetch and install the ISIS binaries.

  2. Fetch the ISIS data.

  3. Add the ISIS executables to your path:

    • bash: export PATH="/path/to/isis/bin:${PATH}"

    • csh: setenv PATH "/path/to/isis/bin:${PATH}"

  4. Set the ISISDATA environmental variable to point to where your ISIS data was downloaded, per the installation link above. For example, in the bash shell, this is done as follows:

    export ISISDATA="/path/to/isisdata"

    Check that the directory $ISISDATA/base exists.

  5. Install Stereo Pipeline and set the PATH variable as above.

  6. Try it out. See Section 4.1 for a quick Lunar example which does not require installing ISIS or its supporting data as above, Section 4.2 for an example using Mars images and ISIS data, Section 5 for DigitalGlobe Earth data, and many other examples in Section 8.

2.3.2. Earth images

Processing Earth images is described in the data processing tutorial in Section 5. See also examples for ASTER (Section 8.23), Pleiades (Section 8.27), SkySat (Section 8.31), and many more in Section 8.

2.3.3. Aerial and historical images

Fetch the software as above. Processing images without accurate camera pose information is described in Section 9.1. See also examples for declassified satellite images in Section 8.32.

2.4. System requirements

To run ASP, a computer cluster sharing storage and connected via ssh is needed (Section 8.22).

As a rule of thumb, for images on the order of 20,000 x 20,000 pixels, a machine with 40 GB of RAM and 16 cores could likely produce a terrain model in 4 - 20 hours. There is a lot of uncertainty here, and much depends on the choice of the stereo algorithm (Section 6.1.1), and if mapprojection is employed (Section 6.1.7).

1 TB of storage or more is suggested.

2.5. Common errors

Here are some errors you might see, and what it could mean. Treat these as templates for problems. In practice, the error messages might be slightly different.

Error: **ERROR** Unable to initialize camera model in Camera Factory.

**PROGRAMMER ERROR** Unable to create a shape model from
  given target and pvl.

**I/O ERROR** Unable to open [$ISISDATA/<Some/Path/Here>].
Stereo step 0: Preprocessing failed

You need to set up your ISIS environment or manually set the correct location for ISISDATA (Section 2.3.1).

bash: stereo: command not found

You need to add the bin directory of your deployed Stereo Pipeline installation to the environmental variable PATH (Section 2.3.1).

/bin/sh: camrange: command not found

You need to add the bin directory of your ISIS installation to your path (Section 2.3.1).

Cache size (500 MB) is larger than the requested maximum cache size

Consider increasing --cache-size-mb for your program. This also may be a sign of large input TIF images being stored in blocks as tall or as wide as the image. The storage scheme of an image can be examined with the gdalinfo -stats command, and an image can be rewritten with square blocks using the command:

gdal_translate -co compress=lzw -co TILED=yes -co INTERLEAVE=BAND \
  -co BLOCKXSIZE=256 -co BLOCKYSIZE=256 input.tif output.tif

If the new images are used instead, that warning should go away and the processing time should go down. Both gdalinfo and gdal_translate are included with ASP.