Skip to content

Installing the Windows Subsystem for Linux (WSL)

Jump to bottom
Bob Yantosca edited this page Oct 11, 2023 · 32 revisions

The Windows Subsystem for Linux allows you to run a Linux session from within your Windows environment. You can then connect to other machines (like Cannon) from this Linux session.

Prerequisites

  • Windows 11 (or later)
  • Windows 10 version 2004 (build #19041) and later

Installation instructions

  1. Open Windows Powershell:

    • Click on the Windows menu (or hit the Windows key)
    • Type Powershell in the search bar
    • Click on Run as administrator

    On some versions of Windows 11, you may see a Terminal (Admin) option when you right click on the Start button. This will also launch a PowerShell in administrator mode.

  2. Install WSL with Ubuntu Linux.

    • NOTE: your-windows-username in the PowerShell prompt will be replaced by your Windows login name.
    PS C:\Users\your-windows-username> wsl --install -d ubuntu

    Upon successful completion, you will see these messages:

    Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Ubuntu
Ubuntu has been installed.
The requested operation is successful. Changes will not be effective until the system is rebooted.

  3. Make sure you are running WSL version 2:

    PS C:\Users\your-windows-username> wsl --set-default-version 2

    Upon successful completion, you will see these messages:

    For information on key differences with WSL 2 please visit https://aka.ms/wsl2
The operation completed successfully.

  4. Apply all recent updates to WSL:

    PS C:\Users\your-windows-username> wsl --update

    If there are no updates, you will see this message:

    The most recent version of Windows Subsystem for Linux is already installed.

  5. Reboot your system so that the changes will take effect. When you log back in, you may see a window pop up with the message:

    Ubuntu is already installed.
Launching Ubuntu...
Installing, this may take a few minutes.

    If you don't see this window, then open a new PowerShell window (as administrator) and type wsl at the prompt. This should start updating Ubuntu and you should see the above message.

    If it seems like this step is taking a long time, hit ENTER to proceed.

  6. You will be prompted to specify your Linux username and password. You will see this prompt:

    Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username:

    Then it will ask you to type a password. This can be different than your Windows password.

    New password:
Retype new password:

    After typing those in you will see the Linux prompt instead of the PowerShell prompt.

    your-linux-username@localhost~#
    • your-linux-username will be replaced by what you specified for your Linux username.
    • localhost will be the name of your computer. This indicates that you are now in a Linux session rather than in Windows.

  7. Change to your Linux home directory by typing

    your-linux-username@localhost~# cd $HOME

  8. Install several common You will do this with the apt package manager. Type the following commands at the Linux prompt.

    • NOTE: For clarity, we have omitted the Linux prompts below.
    • NOTE: Comments beginning with # are provided, but you don't have to type these.
    sudo apt update -y && sudo apt upgrade -y     # Get the latest packages from Ubuntu
sudo apt install -y git-gui                   # Git GUI (NOTE: Git is installed by default)
sudo apt install -y gitk                      # GitK browser
sudo apt install -y xserver-xorg              # X11 server
sudo apt install -y x11-apps                  # Basic X11 applications (e.g. xeyes)
sudo apt install -y xfonts-75dpi              # Fonts for X11
sudo apt install -y xfonts-100dpi             # Fonts for X11
sudo apt install -y fonts-dejavu              # DejaVu fonts (used by several apps)
sudo apt install -y emacs                     # Emacs editor (useful for editing configuration files)
sudo apt install -y bzip2                     # File zip/unzip utility
sudo apt install -y evince                    # PDF viewer
sudo apt install -y gfortran                  # gfortran (for building code locally)
sudo apt install -y libtool                   # Needed to build emacs vterm module
sudo apt install -y libtool-bin               # Needed to build emacs vterm module
sudo apt install -y cmake                     # Needed to build emacs vterm module

  9. Set your locale to en_US with:

    sudo update-locale LANG=LANG=en_US.UTF-8 LANGUAGE

  10. Try opening the xeyes program to test if the X11 server is working. If successful, you will see a pair of eyes on the screen. (Don't laugh, this is the standard tool used to test if X11 forwarding is happening.)

xeyes

  1. Copy your private keys to the ~/.ssh folder.

  2. Shutdown WSL so that all of the settings can be saved. This will return you to the PowerShell prompt.

wsl --shutdown

Additional setup steps

  1. Tell Windows that it should do the graphical rendering locally. Otherwise the rendering will be done on the remote machine, which will incur a noticeable latency. Add these lines to your .bash_profile file:

    # Tell X11 programs to render on Windows, not linux, side
# (cf https://docs.mesa3d.org/envvars.html)
export LIBGL_ALWAYS_INDIRECT=1

  2. Add an exception to your antivirus software for WSL. Otherwise, your antivirus software will attempt to continually scan data packets flowing into and out of your Linux session, which can cause heavy latency. See this post for more information.

  3. Install GCPy and its Python environment. See these instructions for more information.

Connection instructions

  1. If WSL is not running then open a Windows PowerShell (see above) and type:
PS C:\Users\you> wsl
  1. To log in to Cannon, type:
ssh your-Cannon-username@login.rc.fas.harvard.edu
  1. Once you have logged into Cannon you can load your software modules as you normally would.

Clone this wiki locally