Using CIAO on Windows Subsystem for Linux (WSL)

Unsupported

CIAO is not officially supported on Windows Subsystem for Linux (WSL). The CXC has not performed the same formal baseline testing required to certify WSL as is done to vet other platforms (Linux and macOS).

However, based on informal feedback from some users, WSL does appear to be compatible with CIAO's Linux builds. Below are some tips on using CIAO with WSL.

Install WSL

The first step is to install Windows Subsystem for Linux (WSL), specifically WSL2, on your Windows machine. Microsoft provides a useful installation guide.

Note

Users will need to be using WSL2 to use CIAO. The original WSL does not provide an X11 server required to run SAOImageDS9 and make plots with matplotlib.

Users with the original WSL will need to upgrade to WSL2.

Please note that users may need to have Administrator access to install WSL and Linux.

Install Linux

WSL requires special builds of Linux. There are a few different Linux distributions which provide WSL compatible builds. Beginners will probably find Ubuntu the easiest Linux distribution to get started with.

Ubuntu provides instructions on how to install the (current) latest Long Term Support (LTS) release 24.04 using both the Microsoft Store and using the command line in the terminal.

Install X-11 libraries

Most CIAO commands will be run either from the command line in the terminal or optionally in a Jupyter Notebook. However, to use the SAOImageDS9 image display tool and/or to create plots using matplotlib, users will need to install the X11 libraries. For Ubuntu the commands to run are

sudo apt update
suso apt upgrade
sudo apt install x11-apps

Installing the x11-apps will also install all the X11 libraries CIAO needs.

Note

SAOImageDS9 does provide a native Windows installation; however it will not work well with CIAO due to issues with spaces in folder and file names as well as how ASCII files are read/written. WSL users should use the Linux version of ds9 packaged with CIAO.

Install CIAO

Finally users can then install CIAO using either the ciao-install script or using the conda create command.

Please be sure to run the smoke tests to ensure that the setup is functional.

Considerations

WSL is not meant to function as a production environment. Compared to running Linux on the same hardware (ie 'on bare metal'), WSL is noticeably slower (although WSL2 is much faster than the original WSL).

CIAO does not support directories (folders) and/or file names with special characters including spaces, quotes, braces, brackets, and any non-ASCII Unicode characters. These are common with Windows systems.

WSL allows users to run both Windows and Linux commands in the same terminal window. However, after setting up for CIAO, users will probably be unable to run any Windows commands. This is because CIAO modifies the PATH and due to the issue with special characters noted above, it will mess up PATHs to Windows executable which live in folders like "C:\Program Files" (space in folder name).