Installation for Windows

We currently provide 3 different ways to install SCT on Windows machines:

Windows Subsystem for Linux (WSL) installation

Windows Subsystem for Linux (WSL) makes it possible to run native Linux programs on Windows 10. Here, WSL is used to install the Linux version of SCT within Windows (as opposed to the native Windows version).

Basic installation (No GUI)

  1. Make sure that your version of Windows 10 is up to date before continuing.

    • In Windows, search for “System Information” and open the app. In the “Version” field, make sure that you are running “Build 19041” or higher.

    • Then, search for “Powershell” in your Start Menu, then right-click and “Run as administrator”. Then run the following command:

      wsl --update

    • If this command is successful, then you can proceed to the next step. Otherwise, please try the following troubleshooting steps:

  2. Install an Ubuntu distribution in Windows Subsystem for Linux (WSL)

    • In Windows, search for “Powershell” in your Start Menu, then right-click and “Run as administrator”.

    • In PowerShell, type the following command and press enter:

      wsl --install

    • After this command finishes, you will be prompted to restart your computer.

    • After restarting, the installation should automatically resume, and you will be able to create a user account inside Ubuntu by selecting a username and password.

  3. Choose the WSL version (1/2).

    By default, Microsoft’s instructions will create an Ubuntu environment using Version 2 of WSL. While version 2 has been tested to work with SCT, our development team tests more thoroughly using Version 1 of WSL (due to better support from GitHub Actions).

    Because of this, we recommend that you convert the WSL2 Ubuntu environment to use WSL1 before continuing. To do this, first close Ubuntu, then re-open Powershell and run the following command:

    wsl --list --verbose

    If WSL installed correctly, you should see a list of installed distributions (as well as their WSL versions). Find the name of the distribution you just installed (which should be something like Ubuntu or Ubuntu-20.04), then specify that name in the following command:

    wsl --set-version Ubuntu 1

    After you run this command, you can then run wsl --list --verbose again to check that the distribution has changed from WSL2 to WSL1.

  4. Environment preparation

    Now that you have set up an Ubuntu environment with WSL, please open Ubuntu and run the following commands to install various packages that will be needed to install SCT.

    sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get -y install gcc unzip python3-pip python3 psmisc net-tools git gfortran libjpeg-dev

  5. Install SCT

    First, download SCT by running the following commands in Ubuntu:

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

    To select a specific release, replace X.Y below with the proper release number. If you prefer to use the development version, you can skip this step.

    git checkout X.Y

    Install SCT:

    ./install_sct -y

    Note

    At the end of this installation step, you may see the following warnings:

    Check if figure can be opened with matplotlib.......[FAIL] (Using non-GUI backend 'agg')
Check if figure can be opened with PyQt.............[FAIL] ($DISPLAY not set on X11-supporting system)

    This is expected, because WSL does not come with the ability to display GUI programs by default. Later on in this page, there will be optional GUI settings you can configure for WSL to address these warnings.

    To complete the installation of SCT, run:

    source ~/.bashrc

    You can now use SCT. Your local C drive is located under /mnt/c. You can access it by running:

    cd /mnt/c

WSL Installation with GUI (Optional)

If you would like to use SCT’s GUI features, or if you would like to try FSLeyes within the same Ubuntu environment, first complete the previous “Basic Installation” section, then continue on to the steps below.

  1. Download and install VcXsrv, a program that makes it possible to run Linux GUI programs installed with WSL.

  2. Run the newly installed XLaunch program, then click the following settings:

    • On the “Display settings” page, click “Next”.

    • On the “Client startup” page, click “Next”.

    • On the “Extra settings” page, check the “Disable access control” box, then click “Next”.

    • Click “Finish”, then click “Allow access” when prompted by Windows Firewall.

    • You should now see the X Server icon running in the bottom-right system tray in your taskbar.

    Note

    XLaunch must be running each time you wish to use GUI programs in WSL.

  3. Next, run the following commands in Ubuntu, depending on the version of WSL you are using.

    WSL1:

    echo "export DISPLAY=localhost:0.0" >> ~/.bashrc
echo "export LIBGL_ALWAYS_INDIRECT=0" >> ~/.bashrc
source ~/.bashrc

    WSL2:

    echo "export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf 2>/dev/null):0.0" >> ~/.bashrc
echo "export LIBGL_ALWAYS_INDIRECT=0" >> ~/.bashrc
source ~/.bashrc

  4. Finally, run the sct_check_dependencies command in Ubuntu to verify that matplotlib and PyQt figures can be opened by SCT.

  5. Optionally, you can install FSLeyes using the following commands:

    source ${SCT_DIR}/python/etc/profile.d/conda.sh
conda create -c conda-forge -p ~/fsleyes_env fsleyes -y
sudo ln -s ~/fsleyes_env/bin/fsleyes /usr/local/bin/fsleyes

    These instructions will install FSLeyes into a fresh conda environment, then create a link to FSLeyes so that you can use the fsleyes command without having to activate the conda environment each time.

Docker installation

Docker is a portable (Linux, macOS, Windows) container platform.

Basic Installation (No GUI)

First, install Docker Desktop using the WSL 2 backend. Then, follow the example below to create an OS-specific SCT installation.

Docker Image: Ubuntu

First, launch Docker Desktop, then open up a new Powershell or Command Prompt window and run the commands below:

# Start from the Terminal
docker pull ubuntu:22.04
# Launch interactive mode (command-line inside container)
docker run -it ubuntu:22.04
# Now, inside Docker container, install dependencies
apt-get update
apt install -y git curl bzip2 libglib2.0-0 libgl1-mesa-glx libxrender1 libxkbcommon-x11-0 libdbus-1-3 gcc
# Note for above: libglib2.0-0, libgl1-mesa-glx, libxrender1, libxkbcommon-x11-0, libdbus-1-3 are required by PyQt
# Install SCT
git clone https://github.com/spinalcordtoolbox/spinalcordtoolbox.git sct
cd sct
./install_sct -y
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:
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_v6.0"
docker commit <CONTAINER_ID> <IMAGE_NAME>/ubuntu:ubuntu22.04

Enable GUI Scripts (Optional)

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

  1. Open another Terminal

  2. List current docker images

    docker ps -a

  3. Save container as new image

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

  4. Install VcXsrv.

  5. Launch an X11 Server with XLaunch

  • Run XLaunch, which should have been installed by default.

  • Check ‘Multiple Windows’ and set the display number to 0, which you will need later. (The default display number -1 will automatically detect the display number, unless you are running a setup with multiple monitors it will typically use 0)

  • Then, you can click Next, select ‘Start no Client’ then click Next

  • Uncheck ‘Native opengl’ and check ‘Disable Access Control’ then click Next, then click Finish.

  1. Determine the IPv4 address of the virtual Ethernet Adapter by running ‘ipconfig’ in Powershell or the Command Prompt, then looking at the Ethernet adapter vEthernet (WSL) entry.

  2. In your Terminal window, run the following command, filling in the IP address, display number, and image name noted earlier:

    docker run -it --rm -e DISPLAY=<IPv4_ADDRESS>:<DISPLAY_NUMBER> -e XDG_RUNTIME_DIR=/tmp/runtime-root <IMAGE_NAME>/ubuntu:ubuntu22.04

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

    mkdir /tmp/runtime-root
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.