Skip to content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Installing ISIS

Prerequisites

Conda

If you don't have conda yet, download and install it. We recommend getting conda through MiniForge.

# Via Miniforge:
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
x86 emulation on ARM Macs - Rosetta

If you have an ARM mac and want to run the x86 version of ISIS, you will need Rosetta.

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

Conda Environment

# Create conda environment, then activate it.
conda create -n isis 
conda activate isis

# ARM Macs Only - Setup the new environment as x86_64
export CONDA_SUBDIR=osx-64

#Create a new conda environment to install ISIS in
conda create -n isis python>=3.9

#Activate the environment
conda activate isis

# ARM Macs Only - Force installation of x86_64 packages, not ARM64
conda config --env --set subdir osx-64

Channels

# Add conda-forge and usgs-astrogeology channels
conda config --env --add channels conda-forge
conda config --env --add channels usgs-astrogeology

# Check channel order
conda config --show channels
Channel Order: usgs-astrogeology must be higher than conda-forge

Show the channel order with:

conda config --show channels

You should see:

channels:
    - usgs-astrogeology
    - conda-forge
    - defaults

If conda-forge is before usgs-astrogeology, add usgs-astrogeology again to bring up. Set channel priority to flexible instead of strict.

conda config --env --add channels usgs-astrogeology
conda config --env --set channel_priority flexible

Downloading ISIS

The environment is now ready to download ISIS and its dependencies:

conda install -c usgs-astrogeology isis

conda install -c usgs-astrogeology/label/LTS isis

conda install -c usgs-astrogeology/label/RC isis

conda install -c usgs-astrogeology/label/dev isis

Environmental Variables

ISIS requires these environment variables to be set in order to run correctly:

  • ISISROOT - Directory path containing your ISIS install
  • ISISDATA - Directory path containing the ISIS Data Area
Setting Environmental Variables

The Conda Env method is recommended, and the Python Script automates that method:

Requires Conda 4.8 or above

Check your conda version, and update if needed:

# Check version
conda --version

# Update
conda update -n base conda

  1. Activate your ISIS environment.

    conda activate isis

# Now you can set variables with:
# conda config vars set KEY=VALUE

  2. This command sets both required variables (fill in your ISISDATA path):

    conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[your data path]

  3. Re-activate your isis environment. 

    conda deactivate
conda activate isis

The environment variables are now set and ISIS is ready for use every time the isis conda environment is activated.

By default, running this script will set ISISROOT=$CONDA_PREFIX and ISISDATA=$CONDA_PREFIX/data:

python $CONDA_PREFIX/scripts/isisVarInit.py

You can specify a different path for $ISISDATA using the optional value:

python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]

Now every time the isis environment is activated, $ISISROOT and $ISISDATA will be set to the values passed to isisVarInit.py. This does not happen retroactively, so re-activate the isis environment:

conda deactivate
conda activate isis

export sets a variable in your current shell environment until you close it. Adding export commands to your .bashrc or .zshrc can make them persistent.

export ISISROOT=[path to ISIS]
export ISISDATA=[path to data]

Use the python script per instructions from the old readme.

The ISIS Data Area

Many ISIS apps need extra data to carry out their functions. This data varies depending on the mission, and may be quite large, so it is not included with ISIS; You will need to download it separately.

Installation Complete

If you followed the above steps and didn't encounter any errors, you have completed your installation of ISIS.

Updating ISIS

If ISIS was already installed with Conda, you can update it with:

conda update -c usgs-astrogeology isis

conda update -c usgs-astrogeology/label/LTS isis

conda update -c usgs-astrogeology/label/RC isis

Uninstalling ISIS

To uninstall ISIS, deactivate the ISIS Conda Environment, and then remove it. If you want to uninstall conda as well, see your conda installation's website (Miniforge if you installed conda with the above instructions).

conda deactivate
conda env remove -n isis

ISIS in Docker

The ISIS production Dockerfile automates the conda installation process above. You can either build the Dockerfile yourself or use the usgsastro/isis image from DockerHub.

docker run -it usgsastro/isis bash

Download the production Docker file, build, and run it:

# Build
docker build -t isis -f production.dockerfile .

# Run
docker run -it isis bash

Mounting the ISIS data area

Usually you'll want to mount an external directory containing the ISIS data. The data is not included in the Docker image.

docker run -v /my/data/dir:/opt/conda/data -v /my/testdata/dir:/opt/conda/testData -it usgsastro/isis bash

Then download the data into /my/data/dir to make it accessible inside your container.