
Setting Up WSL2: An Extensive Guide
The advent of the Windows Subsystem for Linux (WSL) has brought about a paradigm shift in the way developers operate on Windows-based systems in recent years. The Windows Subsystem for Linux (WSL) enables the seamless execution of a GNU/Linux environment on Windows, sans modification, and minus the resource-intensive nature of a virtual machine.
In this article, I will be sharing my personal approach to installing and configuring an Ubuntu instance on a fresh WSL2 host. This comprehensive guide is tailored to individuals with a foundational level of technical literacy while also being accessible to beginners.
Install WSL2
If you have not yet installed WSL2, this is the first step towards a more seamless Linux experience on your Windows machine. WSL2, or Windows Subsystem for Linux version 2, is a compatibility layer that enables native execution of Linux binaries on Windows 10 and Windows Server 2019. It provides significant performance enhancements over WSL1, full system call compatibility, and native Docker container execution.
First, you must ensure that your Windows version supports WSL2. You can do this by verifying your Windows version; Windows 10 version 1903 or later is required for WSL2.
After confirming your version, you can proceed with the installation. Microsoft has provided detailed instructions on how to install WSL2, and it is recommended that you follow the guide directly from their website for the most accurate and up-to-date information.
In brief, you’ll be following these steps:
- Enable the WSL and Virtual Machine Platform optional features.
- Set WSL2 as your default version.
- Install a Linux distribution, such as Ubuntu.
In addition to its comprehensive documentation, Microsoft’s guide provides additional instructions for upgrading from WSL1 to WSL2 and resolving common technical issues.
As always, take care when making system-level changes, and don’t hesitate to seek out help if you encounter any difficulties.
For further information, visit Microsoft’s official guide on installing WSL2.
As of November 2022, WSL is now available as a Windows Store app for both Windows 10 and Windows 11. This means previous tutorials related to installing WSL as a Windows feature are no longer required.
To begin, run the installation command as an administrator in Powershell
:
1wsl --install
This command will install a fully up-to-date version of WSL2, as well as the Ubuntu distribution.
Configure Ubuntu

Once the installation completes, you’ll need to configure the Ubuntu environment to fit your needs. This includes setting up your shell, updating Ubuntu, and installing any necessary software.
Update and Upgrade Ubuntu
To ensure that your Ubuntu system is up-to-date, it is essential to update your package list and upgrade any outdated packages. This can be achieved by executing the following commands:
1sudo apt update -y2sudo apt upgrade -y
This keeps your system up to date by delivering the most recent security updates and bug fixes.
Install Zsh
Now let’s proceed with the installation of zsh
and change your default shell to it. The command usermod
changes the user login shell, where -s
stands for shell and $(whoami)
returns your username:
1sudo apt install zsh2sudo usermod -s /usr/bin/zsh $(whoami)3sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
You’ll also want to install Starship, a quick and customisable shell prompt that displays important information as you work:
1curl -sS https://starship.rs/install.sh | sh
For an enhanced shell experience, it is recommended to install Starship, a fast and customizable prompt for any shell:
1git clone https://github.com/zsh-users/zsh-history-substring-search ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-history-substring-search
Install GitHub - ryanoasis/nerd-fonts
Nerd Fonts is a collection of over 50 patched fonts for developers. You can install ‘nerd-fonts’ on your Windows host using Chocolatey, a software management automation tool, so that the terminal displays the correct symbols:
1 choco install nerd-fonts-hack
Make Sure Git is Installed
Git
is a distributed version control system and is a necessary tool for most developers. To install it, use the following command:
1sudo apt install git
Copy SSH keys and CHMOD Them
SSH keys provide a secure way of logging into a server with no need for a password. First, you’ll need to copy any private keys you have into the correct directory ~/.ssh
. The public key (.pub
file) should have a permission of 644 (-rw-r--r--)
and the private key (id_rsa
) should have 600 (-rw-------)
.
Once you have copied the keys, add them to the authorized_keys
file:
1cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
Then, ensure your keys have the correct permissions. This command recursively removes all “group” and “other” permissions for the ~/.ssh/
directory:
1chmod -R go= ~/.ssh
Clone Dotfiles
Next, clone your dotfiles
repository. Here’s an example using a hypothetical repository:
1git init23git remote -v4git pull origin master
Configure Git Credential Store
To prevent git
from asking for your username and password every time you perform a repository operation, set git
to use the credential memory cache:
1git config credential.helper store
Remove Password
For those who don’t want to enter their password every time they use sudo
, modify the sudoers.d
file to disable the password prompt:
1sudo vim /etc/sudoers.d/dan
Add the following line:
1MY_USERNAME ALL=(ALL) NOPASSWD:ALL
Replace MY_USERNAME
with your actual username. If you don’t, you’ll receive an error saying no valid sudoers sources found
.
Setup Development Environments

This is the part where you set up the software required for your development needs. This can range from programming languages like Python, Rust or Go to package managers such as npm
and yarn
.
Install NVM, Node.js and Yarn Package Manager
NVM
(Node Version Manager) allows you to install and manage multiple versions of Node.js. After installing NVM
, we’ll use it to install the latest Long Term Support (LTS) version of Node.js. Yarn
is a reliable and fast dependency manager for Node.js:
1curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash2nvm install --lts3npm install --global yarn
Install Python
Python is a popular, general-purpose programming language. To install Python and its development headers:
1sudo apt-get install python3 python3-dev -y
Install Rust
Rust
is a systems programming language that runs blasingly fast and prevents segfaults, guaranteeing thread safety. To install Rust
, download and execute the following script from the official website:
1curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Install LSD
LSD
is a modern replacement for the traditional ls
command. It provides more features and better defaults. It is also significantly faster than all other ls
variants:
1cargo install lsd
Install PostgreSQL
PostgreSQL is an advanced open-source relational database. It provides a robust implementation of SQL, with advanced features such as stored procedures and triggers. To install PostgreSQL, you’ll need to update your Ubuntu package list and then install the necessary packages:
1sudo apt update2sudo apt install postgresql postgresql-client postgresql-client-common postgresql-common postgresql-contrib -y
Verify the installed version of PostgreSQL with:
1psql --version
Start the PostgreSQL service:
1sudo service postgresql start
Now, we will log in as the postgres
user and launch psql
, the command-line interface to PostgreSQL:
1sudo -i -u postgres2psql
Set a password for the postgres
user:
1ALTER USER postgres PASSWORD 'password';
To connect to the PostgreSQL server from a Windows client like pgAdmin, you can use the IP address displayed by the ip route
command inside WSL.
Install Go
Go (often referred to as Golang) is a statically typed, compiled programming language designed at Google. It provides excellent support for concurrent programming and is highly efficient. The following commands will install Go and add it to your PATH:
1sudo rm -rf /usr/local/g2wget <https://go.dev/dl/go1.20.1.linux-amd64.tar.gz>3sudo tar -C /usr/local -xzf go1.20.1.linux-amd64.tar.gz4
5export PATH=$PATH:/usr/local/go/bin6
7go version
Install Neovim
Neovim is a highly configurable text editor built to enable efficient text editing. It is an extension of Vim, with many new and improved features. The following commands will install Neovim and make it the default editor:
1sudo apt update2sudo apt install libfuse23sudo apt install unzip4
5curl -LO <https://github.com/neovim/neovim/releases/latest/download/nvim.appimage>6chmod u+x nvim.appimage7sudo mv ./nvim.appimage /usr/local/bin/nvim.appimage8
9CUSTOM_NVIM_PATH=/usr/local/bin/nvim.appimage10# Set the above with the correct path, then run the rest of the commands:11set -u12sudo update-alternatives --install /usr/bin/ex ex "${CUSTOM_NVIM_PATH}" 11013sudo update-alternatives --install /usr/bin/vi vi "${CUSTOM_NVIM_PATH}" 11014sudo update-alternatives --install /usr/bin/view view "${CUSTOM_NVIM_PATH}" 11015sudo update-alternatives --install /usr/bin/vim vim "${CUSTOM_NVIM_PATH}" 11016sudo update-alternatives --install /usr/bin/vimdiff vimdiff "${CUSTOM_NVIM_PATH}" 110
Install AstroVim
AstroVim is a Neovim configuration aiming to provide an out-of-the-box experience with the best plugins for efficient development. It leverages the power of the Neovim 0.5 API and Lua to provide fast and snappy performance. Here are the steps to install and set up AstroVim:
First, you may want to back up any existing Neovim configuration:
1mv ~/.config/nvim ~/.config/nvim.bak2mv ~/.local/share/nvim/site ~/.local/share/nvim/site.bak
Ensure your system is up-to-date and install some prerequisite packages:
1sudo apt-get update && sudo apt-get upgrade2sudo apt-get install build-essential3sudo apt-get install aptitude4sudo apt-get install libstdc++6
Install some necessary tools:
1cargo install tree-sitter-cli2sudo apt-get install ripgrep3
4LAZYGIT_VERSION=$(curl -s "<https://api.github.com/repos/jesseduffield/lazygit/releases/latest>" | grep '"tag_name":' | sed -E 's/.*"v*([^"]+)".*/\\1/')5curl -Lo lazygit.tar.gz "<https://github.com/jesseduffield/lazygit/releases/latest/download/lazygit_${LAZYGIT_VERSION}_Linux_x86_64.tar.gz>"6sudo tar xf lazygit.tar.gz -C /usr/local/bin lazygit7lazygit --version8
9sudo add-apt-repository ppa:daniel-milde/gdu10sudo apt-get update11sudo apt install gdu12
13rustup update stable14cargo install bottom --locked
Clone the AstroVim configuration into your local Neovim configuration directory:
1git clone https://github.com/AstroNvim/AstroNvim ~/.config/nvim2nvim
Copy the user configuration example (or your own if you have one) to your user configuration directory:
1cp -r ~/.config/nvim/lua/user_example/ ~/.config/nvim/lua/user/
Visit this link for more information about installing libstdc
.
Install Additional/Work-related Dependencies
Here are a few examples of installing additional dependencies. Be sure to modify these instructions according to your specific needs. The following commands will install Google Cloud SDK, kubectl, Git LFS, PHP and its extensions, Composer, and Helm:
1sudo apt-get install apt-transport-https ca-certificates gnupg2echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list3curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -4sudo apt-get update && sudo apt-get install google-cloud-cli5sudo apt-get install kubectl6
7curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash8sudo apt-get install git-lfs9
10sudo apt-install php-curl php-simplexml11
12sudo apt update13sudo apt install php-cli unzip14cd ~15curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php16HASH=`curl -sS https://composer.github.io/installer.sig`17php -r "if (hash_file('SHA384', '/tmp/composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"18sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer19
20curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null21sudo apt-get install apt-transport-https --yes22echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list23sudo apt-get update24sudo apt-get install helm
Additional Steps
Please keep in mind that the actions below are only required if you plan to execute certain apps within the Windows Subsystem for Linux (WSL). This is generally necessary when services running in WSL cannot be accessed directly from the Windows host.
For applications like Docker, it is typically recommended to utilise the Docker Desktop application for Windows instead of installing it directly onto WSL. Docker Desktop is specifically designed to run on Windows and offers seamless integration with the host operating system, as well as a user-friendly interface.
Similarly, for API testing with Postman, the application is also available as a native Windows program. Therefore, you may find it more convenient and efficient to run Postman directly from Windows.
However, installation of these applications within WSL may be required under specific conditions. For example, if you need to interact with services that are not readily accessible from the host system, or if you want to maintain a consistent workflow within the Linux environment.
Consider that activating such functionalities may necessitate additional configuration steps, such as enabling systemd
in WSL, as described in earlier sections of this guide. Always be mindful of your specific development needs and adjust your environment accordingly.
Install Docker
Docker is an open-source platform that automates the deployment, scaling, and management of applications using containerization. Follow the instructions provided in the official Docker documentation to install Docker on Ubuntu.
Here is an example of the steps I take when installing Docker on WSL directly.
1sudo apt-get remove docker docker-engine docker.io containerd runc2sudo apt-get update3sudo apt-get install \4 ca-certificates \5 curl \6 gnupg \7 lsb-release8
9sudo mkdir -m 0755 -p /etc/apt/keyrings10curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg11
12echo \13 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \14 $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null15
16sudo apt-get update17sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin18sudo service docker start19
20sudo groupadd docker21sudo gpasswd -a dan docker22docker run hello-world
Install Google Chrome
Google Chrome is a cross-platform web browser developed by Google. To install Google Chrome, execute the following commands:
1wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb2sudo dpkg -i google-chrome-stable_current_amd64.deb3sudo apt -f install4sudo apt install google-chrome-stable
Install Postman
Postman is a popular tool for testing APIs. However, installation requires using snapd
package manager and the systemd
init system, which isn’t supported in WSL out of the box. As of Windows 11, you can enable systemd
support in WSL. Follow the guide in this Microsoft blog post to set up systemd
.
Once systemd is enabled, you can install Postman or other software that relies on it. This will increase the range of tools available for your development environment.
Note that this step is only necessary if you need to run specific applications inside WSL. In many cases, you might be able to run Docker and Postman directly from the Windows host instead.
To enable systemd
, edit the wsl.conf
file:
1sudo vim /etc/wsl.conf
Add the following lines to the file:
1[boot]2systemd=true
Afterwards, you need to restart WSL:
1wsl --shutdown
Now, reopen any WSL terminal to start the system with systemd
support. You can now proceed with installing Postman or any other tools that require systemd
.
Remember, creating an optimal development environment requires a careful balance between the tools you need and maintaining the system’s performance and security. Always remember to update regularly, clean up unnecessary files, and only install trusted software from official sources.
Conclusion
And there we have it - a comprehensive guide to setting up a WSL2 instance for personal and development use.
Through this guide, you’ve installed and configured a robust Ubuntu development environment right on your Windows machine, combining the best of both worlds for a unique development experience.
From setting up Zsh and Git to installing various programming languages and databases, you’ve got a powerhouse at your fingertips. So whether you’re coding the next big app or crunching data for insightful analytics, you’re well-equipped for the task. Happy coding!
References & Further Reading
This comprehensive guide to setting up WSL2 with Ubuntu on a Windows host wouldn’t be possible without referring to several online resources. The following references have been instrumental in providing the information necessary to create this guide:
- Windows Subsystem for Linux in the Microsoft Store
- GitHub - ryanoasis/nerd-fonts
- Chocolatey
- NVM - Node Version Manager
- Go Programming Language Download
- Neovim Releases
- AstroVim
- AskUbuntu: Install libstdc
- Docker Engine on Ubuntu
- Systemd Support in WSL
- Setting up WSL 2 for Web Development
- Web Dev setup in WSL2 Kali Linux 2022 Edition - Part 1: Connecting MariaDB and PostgreSQL database across Windows and WSL2
- How to set up a Linux development environment in Windows 10
- Setting up multiple WSL distribution instances | endjin
Images used in the blog are sourced from the following websites:
- Photo by Kevin Ku on Pexels
- Photo by Gabriel Heinzer on Unsplash
- Photo by cottonbro studio on Pexels