Installation for Linux

Warning

If you use Windows Subsystem for Linux (WSL), please refer to the Windows installation section.

Installation Options

Depending on your use case, there are a number of different installation methods available:

Requirements

Supported Operating Systems

  • Debian >=9

  • Ubuntu >= 16.04

  • Fedora >= 19

  • RedHat/CentOS >= 7

GNU Compiler Collection (gcc)

You need to have gcc installed. We recommend installing it via your package manager.

For example on Debian/Ubuntu:

apt install gcc

On CentOS/RedHat:

yum -y install gcc

Install from Package

The simplest way to install SCT is to use an in-place, static version of a tested package release. If you do not have any special circumstances, we recommend using this installation method.

First, navigate to the latest release, then download the install script for SCT (install_sct-<version>_linux.sh). Major changes to each release are listed in the Changelog.

Once you have downloaded SCT, open a new Terminal in the location of the downloaded script, then launch the installer using the bash command. For example, if the script was downloaded to Downloads/, then you would run:

cd ~/Downloads
bash install_sct-<version>_linux.sh

Install from GitHub

If you wish to benefit from the cutting-edge version of SCT, or if you wish to contribute to or test changes to the code, we recommend you install SCT using this method.

  1. Retrieve the SCT code

    Clone the repository and hop inside:

    git clone https://github.com/spinalcordtoolbox/spinalcordtoolbox

cd spinalcordtoolbox

  2. (Optional) Checkout the revision of interest, if different from master:

    git checkout <revision_of_interest>

  3. Run the installer and follow the instructions

    ./install_sct

Install within Docker

Docker is a portable container platform.

In the context of SCT, it can be used to test SCT in a specific OS environment; this is much faster than running a fully fledged virtual machine.

Basic Installation (No GUI)

First, install Docker. Be sure to install from your distribution’s repository.

Note

Docker Desktop for Linux is not recommended if you intend to use the GUI. Instead install the Docker Server Engine, which is separate from the Docker Desktop Engine. For example on Ubuntu/Debian, follow the instructions for installing Docker from the apt repository.

By default, Docker commands require the use of sudo for additional permissions. If you want to run Docker commands without needing to add sudo, please follow these instructions to create a Unix group called docker, then add your user account to it.

Then, follow the example below to create an OS-specific SCT installation (in this case, for Ubuntu 22.04).

# Pull the Docker image for Ubuntu 22.04
sudo docker pull ubuntu:22.04
# Launch interactive mode (command-line inside container)
sudo docker run -it ubuntu:22.04
# Now inside Docker container, install SCT dependencies
apt update
apt install git bzip2 curl gcc git libdbus-1-3 libgl1-mesa-glx libglib2.0-0 libxkbcommon-x11-0 libxrender1
# Note for above: libdbus-1-3, libgl1-mesa-glx, libglib2.0-0, libxkbcommon-x11-0, libxrender1 are required by PyQt
# Install SCT (you can change 7.0 for the version of your choice)
git clone --branch 7.0 https://github.com/spinalcordtoolbox/spinalcordtoolbox.git sct
cd sct
./install_sct -iy
source /root/.bashrc
# Test SCT
sct_testing
# Save the state of the container as a docker image.
# Back on the Host machine, open a new terminal and run:
sudo docker ps -a  # list all containers (to find out the container ID)
# specify the ID, and also choose a name to use for the docker image, such as "sct_v7.0"
sudo docker commit <CONTAINER_ID> <IMAGE_NAME>/ubuntu:ubuntu22.04

Alternatively, you can modify and use this example Dockerfile for SCT.

Enabling GUI Scripts

In order to run scripts with GUI you need to allow X11 redirection. First, save your Docker image if you haven’t already done so:

  1. Open another Terminal

  2. List current docker images

    sudo docker ps -a

  3. If you haven’t already, save the container as a new image

    sudo docker commit <CONTAINER_ID> <IMAGE_NAME>/ubuntu:ubuntu22.04

Then, to forward the X11 server:

Note

The following instructions have been tested with Xorg and xWayland.

Set up may vary if you are using a different X11 server.

  1. Install xauth and xhost on the host machine, if not already installed:

    For example on Debian/Ubuntu:

    sudo apt install xauth x11-xserver-utils

  2. Permit docker access to the X11 Server

    If you are hosting the container from the local machine:

    xhost +local:docker

  3. In your Terminal window, run:

    sudo docker run -it --rm --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix <IMAGE_NAME>/ubuntu:ubuntu22.04``

You can test whether GUI scripts are available by running the following command in your Docker container:

sct_check_dependencies

You should see two green [OK] symbols at the bottom of the report for “PyQT” and “matplotlib” checks, which represent the GUI features provided by SCT are now available.

[EXPERIMENTAL] Install as a pip Package

You should only install SCT this way if you need to access the internal functions of the package for use in a Python environment. As well, doing so comes with some caveats:

  • The installation is done in-place, so the folder containing SCT must be kept around and in the same place it was originally.

  • In order to ensure coexistence with other packages, the dependency specifications are loosened. As a result, it is much more likely that you will be running a combination that has not been tested, which may introduce unpredicable bugs or crashing.

If the installation fails, or you run into errors, please report a bug indicating the dependency versions retrieved using “sct_check_dependencies”, and try again with a clean pip installation/environment.

  1. [Optional] Activate the virtualenv environment you want to install SCT within.

  2. Clone the current SCT repository and enter it.

    git clone https://github.com/spinalcordtoolbox/spinalcordtoolbox

cd spinalcordtoolbox

  3. Checkout the revision of interest, if different from master:

    git checkout <revision_of_interest>

  4. Install numpy:

    pip install numpy

  5. Install SCT using pip:

    If you’re installing within a virtualenv:

    pip install -e .

    Otherwise (you want SCT available in your base environment):

    pip install --user -e .