1.1.9. Windows 10: Windows Subsystem for Linux (WSL)

What to do?

These setup instructions are for setting up Ubuntu on the “Fall Creators Update” (FCU) version of Windows 10, known as the Windows Subsystem for Linux (WSL). This FCU was released in Windows version 1709 around October, 2017.

See this “What’s New” page for more information about the Windows updates since their earlier beta version of having Ubuntu. Mainly, the present installation is a lot easier now. Yippee.

  1. The user must have admin privileges (can run sudo ...). Some steps require an internet connection.

Install Linux

  1. Click here to install WSL 1 (noooot WSL 2), and probably select “Ubuntu 20.04” as your desired flavor of Linux:

Install VcXsrv Windows X Server

  1. Click here to start automatic download:
    Use default installation settings.
  2. Now and forever, first doubleclick on the VcXsrv icon on your Desktop, and then start Ubuntu, for example by typing “ubuntu” in the Windows search bar. (Sorry, not our design!)

  3. To enable copy+paste ability in Ubuntu terminal, right-click on the toolbar at the top of the Ubuntu terminal, and select “Properties”; in the Options tab, make sure the box next to “QuickEdit Mode” is selected.

    You can then paste into a terminal by either right-clicking or hitting the “Enter” key. (To “copy” text that is in the terminal, just highlight it, and then you should be able to right-click to paste; to “copy” text from outside the terminal, you probably need to highlight it and hit “Ctrl+c”.)

  4. Copy+paste:

    echo "export DISPLAY=:0.0" >> ~/.bashrc
    echo "setenv DISPLAY :0.0" >> ~/.cshrc
    echo "export NO_AT_BRIDGE=1" >> ~/.bashrc
    echo "setenv NO_AT_BRIDGE 1" >> ~/.cshrc

    Purpose: First, set DISPLAY properly, so you can open GUIs like afni, suma, etc. Then, avoid having some very-non-necessary GTK warnings from programs.

  5. Close (exit) Ubuntu terminal, so that changes are effected the next time you open it.

More setup tips for Ubuntu+Windows

  1. Install Ubuntu terminal fonts as described under “Bonus: Install the Ubuntu Font for a True Ubuntu Experience” on this page (waaay down).

  2. The default profile “use colors from system theme” shows an all-black terminal. To adjust this to something nicer:
    Go to the terminal’s menu bar,
    Select the Edit tab, then Profile,
    Turn off “use colors …”, and just pick a scheme+palette that you like.
  3. Note:
    In gnome-terminal, things are similar to other Linux implementations. The middle button pastes whatever is highlighted in the WSL terminal or other gnome-terminal: shift-ctrl-c copies, and shift-ctrl-v also pastes.

Transferring data between Ubuntu and Windows

  1. You can “see” your Windows file system from the Ubuntu side, where it appears as /mnt/c/. For example, if your Windows username is USERNAME, then the following would copy a file called FILE.pdf on your Windows Desktop to your current Ubuntu terminal location:

    cp /mnt/c/Users/USERNAME/Desktop/FILE.pdf .
  2. To mount external devices (e.g., a USB) from the Ubuntu side. Let’s say your external device appears as the “G:” drive on Windows when you plug it into a USB port. You could mount that drive from Ubuntu as follows:

    sudo mkdir /mnt/g                # make a mount point location; 'g' is a convenient label here
    sudo mount -t drvfs G: /mnt/g    # mount the external drive to it

    If you had a file FILE.nii on the “G:” drive USB, you could now copy it to your present location with:

    cp /mnt/g/FILE.nii .

    To safely unmount the USB before unplugging it, type:

    sudo umount /mnt/g

    Bonus note: you can mount/unmount network shares in a similar way:

    sudo mkdir /mnt/share
    sudo mount -t drvfs '\\server\share' /mnt/share
    sudo umount /mnt/share

Install prerequisite: AFNI and package dependencies

  1. Start a new Ubuntu session. To check your version, copy+paste:

    lsb_release -a
  2. For …

    Purpose: Complete your life’s ambition to have working AFNI on your Windows computer (though, realize it is Linux that makes this happen!).

Setup Python (opt)

  1. AFNI has very minimal Python requirements—at present, matplotlib and numpy. For example, for the recommended automatic QC output from afni_proc.py, matplotlib is necessary.

    You can use any method to install+manage Python and its dependencies. But we note that we have found Miniconda to be convenient in managing Python environment(s), and it is replicatable across platforms. If you are interested, you can check out this tutorial, which has both verbose and quick instructions.

    But Miniconda is not required.

Prepare for Bootcamp

  1. Copy+paste:

    curl -O https://afni.nimh.nih.gov/pub/dist/edu/data/CD.tgz
    tar xvzf CD.tgz
    cd CD
    tcsh s2.cp.files . ~
    cd ..

    Purpose: Download the Bootcamp class data; untar+unzip it (= open it up); move into the newly opened directory; execute a script to copy the files to $HOME/..

    If no errors occur in the above, and your afni_system_check.py says things are OK, you can delete/remove the tarred/zipped package, using “rm CD.tgz”. If you are really confident, you can also deleted the CD/ directory in the present location.

  2. !Pro tip!: Bring a computer mouse to use at the Bootcamp. It is muuuuch easier to follow the demos that way.

  3. Read+practice with the handy Unix documentation/tutorial.

    Purpose: give you a quick lesson/refresher on using basic Linux shell commands (e.g., ls, cd, less, etc.). It will greatly enhance your bootcamp experience– we promise!

Evaluate setup/system (important!)

  1. Copy+paste:

    afni_system_check.py -check_all
  2. Read the “Please Fix” section at the end. If there are no suggestions, then rejoice! Otherwise, try the suggestion(s) there.

  3. Open up the AFNI and SUMA GUIs, juuuust to make sure all is well:


    Report any crashes!

  4. If stuck, then …

    • … put any error message into an online search, and/or post a question on the Message Board

    • … copy+paste this:

      afni_system_check.py -check_all > out.afni_system_check.txt

      ... and email the file “out.afni_system_check.txt” to an AFNI Guru for advice.

Niceify terminal (optional, but goood)

  1. To improve your life when using the terminal, copy+paste:

    echo 'set filec'    >> ~/.cshrc
    echo 'set autolist' >> ~/.cshrc
    echo 'set nobeep'   >> ~/.cshrc
    echo 'alias ls ls --color=auto' >> ~/.cshrc
    echo 'alias ll ls --color -l'   >> ~/.cshrc
    echo 'alias ltr ls --color -ltr'   >> ~/.cshrc
    echo 'alias ls="ls --color"'    >> ~/.bashrc
    echo 'alias ll="ls --color -l"' >> ~/.bashrc
    echo 'alias ltr="ls --color -ltr"' >> ~/.bashrc

    Purpose: The first commands set up tab autocompletion for tcsh (which should already be enabled for bash, by default). The second set of commands make aliases so that different types of files (“normal” files, zipped files, executables, et al.) and directories are shown using different colors and boldness. It makes it much easier to navigate on a terminal, IMHO.

Keep up-to-date (remember!)

  1. To update your AFNI sometime, copy+paste:

    @update.afni.binaries -d

    That’s it!!

    Purpose: This will automatically download the correct, latest AFNI version to your computer, replacing your old binaries. It will also update the apearch help information. Update often!

  2. To check your AFNI version, copy+paste:

    afni -ver

    Purpose: Report this useful info whenever asking a question on the Message Board!


The record of all changes (new options, new programs, bug fixes, et al.) in AFNI programs is maintained for all to see in the online AFNI History.