WSL2 (Windows Subsystem for Linux version 2)
WSL (Windows Subsystem for Linux) allows you to use Linux on top of Windows natively. WSL2 is the latest version of WSL and is more stable with improved performance and compatibility. If you already have WSL(1), it is easy to convert to WSL2 (see Instructions to convert WSL(1) to WSL2). If your Windows 10 is version 1909 or older, see the “Install WSL2 on Windows 10 (older versions)” section on this page.
Install WSL2 on Windows 10 or 11
- Open Start (Win key) and search for Command Prompt (type directly) in your applications,
right-click and select
Run as administrator
. SelectYes
on the prompt that appears asking if you want to allow the app to make changes to your device. -
Type the following into the Command Prompt, then press
Enter
:wsl --install
- Restart your computer to finish the WSL installation and continue with the Linux distro setup.
- Open Start (Win key) and search for Command Prompt in your
applications, right-click and select
Run as administrator
. SelectYes
on the prompt that appears asking if you want to allow the app to make changes to your device. - At this point, if you are on a newer version of Windows 10 or Windows 11, the command from Step 2 should have installed, in addition to WSL, the latest LTS version of Ubuntu (24.04 LTS at time of writing) as the default distribution. If this is the case, an Ubuntu terminal will open to resume automatic setup, and afterwards will ask you set up a username and password. If this applies to you, skip to Step 9. Otherwise, continue with Step 6.
-
In the Command Prompt, type the following command to view a list of available WSL distros you can install and press Enter:
wsl --list --online
-
Type the following command to install a specific distro (Ubuntu-22.04 recommended) in WSL and press
Enter
(it will start the distro if it has already been installed):wsl --install -d <DISTRO-NAME>
- Restart your computer, open Start (Win key) and search for Ubuntu, and click on the app called Ubuntu or Ubuntu <VERSION-NUMBER>. You should now have the WSL2 Ubuntu 22.04 terminal open. Now, you are ready to rock!
- You will be prompted to
Enter new UNIX username
(this will create a local user account for the Ubuntu WSL instance and you will be automatically logged in to your Ubuntu distro as this user). You can use any combination of alphanumeric characters for your username, but a good choice is<first_initial><last_name>
(e.g.,jsmith
for John Smith). You will then be prompted to enter a new password (choose something easy to remember as you will use it frequently for this course).
From this point on, whenever the instructions specify to “open/type a command in a terminal”, please open/type the command in the Ubuntu application (open Start (Win key), search for Ubuntu, and click Ubuntu or Ubuntu <VERSION-NUMBER>).
Need more help?
- https://learn.microsoft.com/en-us/windows/wsl/install
- https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support#2-install-wsl
Bash shell (in the WSL2 Ubuntu)
You already have it, now that you’ve installed the WSL2!
Git (in the WSL2 Ubuntu)
You already have it, now that you’ve installed the WSL2!
Git configuration
If you have never used Git on your computer, you may have to configure it. The following instructions assume you have already created a GitHub account.
Type the following commands in a terminal. Make sure to use the email associated with your GitHub account.
The user.name
can be any name you want to appear as the author of your commits, but we recommend using the name associated with your GitHub profile.
git config --global user.name "Jane Doe" git config --global user.email "janedoe@example.com" git config --global core.autocrlf true
Tip: You can review your configuration at any time with: git config --list
Creating an SSH key for GitHub
When following the GitHub docs below, make sure to select the Linux instructions.
To authenticate to GitHub from the command line, you will use an SSH key pair, which is more secure than using your GitHub account password directly.
-
In a terminal, check if you have existing SSH keys in the ~/.ssh directory.
A public/private key pair typically has the filename format
id_ALGORITHM
andid_ALGORITHM.pub
. If you have existing key files, use a custom name for your SSH key pair in step 2. -
Generate a new SSH key and add it to the ssh-agent.
- Ensure to use the default file location for saving the key, unless you already have existing keys - in this case, replace just the
id_ALGORITHM
(e.g.,id_ed25519
) part of the file location with an informative keyname likeid_ed25519_github
- Choose a passphrase you can remember easily, as you will need to use it for certain Git commands
- Ensure to use the default file location for saving the key, unless you already have existing keys - in this case, replace just the
-
Confirm your key pair was created by running the command:
You should see two files with your key name, one withls -la ~/.ssh
.pub
(the public key) and one without (the private key - do not share or copy this file!). -
Add the SSH key to your GitHub account.
- Be careful when copying/pasting the public key to not accidentally add spaces or newlines
- Choose Authentication Key for the key type
-
Locally specify the SSH key to use when connecting to GitHub, so that the right "identity" is always used for local Git operations (useful when you have multiple keys).
-
Run the following command (replace
id_ed25519
with your private key's filename if you used a custom key name):printf 'Host github.com\n User git\n IdentityFile ~/.ssh/id_ed25519\n IdentitiesOnly yes\n' >> ~/.ssh/config
-
Then, check that the config was added:
You should see something like:cat ~/.ssh/config
Host github.com User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes
-
Run the following command (replace
In this course, when using a Git command that prompts you for your passphrase, enter the passphrase you set for your private key in step 2.
VSCode (on your Windows)
- Go to this page and click the download
button, then run the
.exe
file. - Leave all the defaults during the installation with the following exception:
- Make sure the box labeled “Register Code as an editor for supported file types” is selected
VSCode extensions
These extensions will allow you to work with WSL2 Ubuntu more seamlessly in VSCode.
- Open Visual Studio Code, click on the Extensions icon in the left sidebar
(or press
Ctrl+Shift+X
), and search for and install the WSL extension (usually, VSCode can automatically detect your WSL Ubuntu installation and remind you to install related extensions). - In a terminal (Ubuntu), type
code .
and pressEnter
. You should see a message readingInstalling VS Code Server
and then a new VSCode window (might be calledGet Started - <USERNAME> [WSL: Ubuntu <VERSION-NUMBER>] Visual Studio Code
) will open up. It should sayWSL
in the bottom left corner of the window. - In the WSL VSCode window, open the Extensions panel again (or
Ctrl+Shift+X
). Search for each of the following extensions and clickInstall
(orInstall in WSL: Ubuntu
, depending on whether you already have the extension installed locally) for the first entry that appears. If noInstall
button is available and the extension is not grayed out, it means it is already installed.
- Python Extension Pack (note: you will need to reload VSCode after installing this)
- Jupyter
- Docker
- WSL
To confirm the extensions have been installed correctly, clear the Extensions search bar.
You should now see an extensions category called WSL: UBUNTU - INSTALLED
(you may also see one for LOCAL - INSTALLED
).
Verify that the extensions you have just installed exist in the list under WSL: UBUNTU - INSTALLED
.
WSL2 Ubuntu terminal in VSCode
You can open the terminal in your WSL VSCode window (if you do not already have
one at the bottom of the window) by navigating to View > Terminal in
the top menu bar (or, Ctrl+`
). This terminal in a WSL VSCode window
is equivalent to the WSL2 Ubuntu terminal we get from opening the Ubuntu app
itself (i.e., like we did from the Start (Win key) menu), but with the
advantage of having all the graphical features of VSCode at your disposal.
Reference: https://code.visualstudio.com/docs/remote/wsl
Python (in the WSL2 Ubuntu)
We are going to install miniconda to manage the Python environment in our WSL2 Ubuntu using the VSCode terminal (alternatively, you can use the WSL Ubuntu terminal directly: open Start (Win key) and search for the Ubuntu app).
-
Type the following lines (separately) into the terminal and press
Enter
after each one:wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh
- A license agreement will be displayed and the bottom of the terminal will read
--More--
. PressEnter
or the space bar until you are prompted withDo you accept the license terms? [yes\|no].
Typeyes
and then pressEnter
. - The installation script will inform you that it is going to install into a
default directory (e.g.,
/home/$USER/miniconda3
). Leave this default and pressEnter
. - When you are asked “Do you wish the installer to initialize Miniconda3 by
running conda init? [yes|no],” type
yes
and pressEnter
. Close the terminal once the installation has finished. - Re-open the Ubuntu terminal. Type
which python
into the terminal and it should return a path (e.g.,/home/$USER/miniconda3/bin/python
).- If you do not see a path like this then please try
cd miniconda3/bin/
then./conda init
, close (or re-open) your terminal, and repeat this step. If your issue is still not resolved skip the following step and contact an instructor on the#help-installation
channel on the Slack workspace.
- If you do not see a path like this then please try
-
Type the following to remove the installation script that was downloaded:
rm ./Miniconda3-latest-Linux-x86_64.sh
Python packages
Open a terminal and type the following commands (press Enter
after each):
conda config --append channels conda-forge conda config --set channel_priority strict conda create -n qlsc612 -y python=3.12 flake8 jupyterlab jupyter nilearn matplotlib seaborn bokeh statsmodels plotly wordcloud conda activate qlsc612
This installation step (conda create
) will take a couple minutes.
The above commands create a new conda Python environment named qlsc612
with all the necessary packages installed for this course.
The last line, conda activate qlsc612
,
will activate this Python environment (the default environment is base
).
Now you are ready to use VSCode to edit your Python script or Jupyter Notebook in your WSL2 Ubuntu distribution.
Reminders:
- You may need to reactivate the
qlsc612
environment each time you start the WSL2 (e.g., in VSCode) withconda activate qlsc612
. - When running a Jupyter notebook in VSCode (remote access to your WSL2 Ubuntu)
you will also need to specify the Python environment (kernel).
There will be a
Select Kernel
button in the top right corner of the Jupyter notebook, click it and select the one reading something like qlsc612 (Python 3.x.y) ~/miniconda3/envs/qlsc612/bin/python. The button should be updated to read qlsc612 (Python 3.x.y). This is the Python environment we have just created for this course, make sure it is the one you are using for later modules.
Docker Desktop for Windows
You should install Docker Desktop after you have successfully installed WSL2.
- Go to this page and click “Docker Desktop for Windows”, then run the downloaded installer.
- When prompted, ensure the “Use WSL 2 instead of Hyper-V option” on the Configuration page is selected.
- Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
- When the installation is successful, click “Close” to complete the installation process. (If the admin account on your computer is different to your user account, you must add the user to the docker-users group. Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users. Right-click to add the user to the group. Log out and log back in for the changes to take effect.)
- Open Start (Win key), search for Docker Desktop in your applications, and click to run the app.
Once Docker Desktop has loaded, in a WSL2 Ubuntu terminal (in VSCode or your Ubuntu app),
type
docker run hello-world
. A brief introductory message should be printed to the screen.
Reminders:
- Whenever you need to use Docker, first make sure that Docker Desktop is running (open Start (Win key) and search for the Docker Desktop app)
- For this course, you should run Docker commands from a WSL2 Ubuntu terminal. However, in general you can also use Docker command-line tools in Command Prompt or PowerShell.
The above step-by-step instructions are distilled from here.