How to Install WSL for Windows 10 - Includes WSL2 Optional Steps

This walkthrough attempts to compile multiple sources and guides on how to install WSL (Windows Subsystem for Linux) to optimize for smart contract development.

Ideally, this will serve as a full guide for functional installation. In many cases, this will serve as just another resource to help optimize the installation for your specific needs.

All the information in this walkthrough can be found in other guides and resources online. They will be presented as used in relevant steps. They will also be listed at the bottom of the post in a Resources section.

Important: At the time of writing, WSL2 is available for use and claims to have superior performance. However, the guide provided by Microsoft requires users to install Windows 10 Insider Preview Build for WSL2. Depending on your circumstance, this may or may not be ideal as it offers the newest releases, but, with them, potential bugs yet to be addressed. This article from howtogeek can help you decide whether or not the Insider Preview Build is ideal for your needs.

We will start with the steps for installing WSL2. If you don’t want to be part of the Windows 10 Insider Preview Build, you can skip step 1 and optional step 4 to install the original WSL, instead of WSL2, without being a part of the Insider Preview Build.

Step 1: Install the Windows 10 Insider Preview Build

  • Open the Start menu and click on Settings. Search for Windows Insider Program.

  • Click “Get Started”.

  • Link and register your Microsoft account.

  • Choose the rate at which you’d like to receive insider preview updates. Fast will be prone to the most bugs with Release Preview being prone to the least. This article may help you determine the best option for your needs.

Step 2: Enable Windows Subsystem for Linux and the Virtual Machine

  • Open the Start menu and click on Settings. In Settings, search for Turn Windows features on or off.

  • You can also do this through the Powershell console if you prefer. The effects should be the same.

  • Restart your computer.

Step 3: Install a Linux Distribution

  • There are a few different ways to install and many Linux distribution variations to choose from. Installing Ubuntu 18.04 LTS through the Microsoft store is recommended by Microsoft here. However, additional installation means and distributions can be found here

  • We will continue with the Microsoft recommendation. Find Ubuntu 18.04 LTS on the Microsoft store here, and click Get.

  • After it’s downloaded, click Launch.


  • The terminal below should appear. After a few minutes, you’ll be prompted to enter a username and password. These are totally unrelated to your Windows username and password, and are only requested upon the first installation. Additional guide on initialization found here.

  • Note: The username will be your default user profile for Linux. Also, you will be prompted to enter your password when using sudo commands, so something easy to remember and type is more convenient.

  • Once accepted, you will have access to the terminal. As you might notice below, a preferred username is all lowercase and accepts no numbers. :sweat_smile:

  • Update and upgrade your Ubuntu distribution with sudo apt update && sudo apt upgrade. Or enter these commands separately like below. When the upgrade command requests permission to use disk space, enter y to continue.

Recommended: Navigating to your Windows projects from this terminal may not be obvious at first. This video can guide you through the set up steps and how to navigate to your projects. It also gives advice for interacting with your Windows projects through your Linux-based terminal. Below is an example of navigating through directories.

Optional Step 4: Install WSL2: For WSL2 installations, there are a couple additional steps and some minor configuration. These steps can be found here.

Step 4: Install nvm, node.js, and npm

  • If you already have node and npm installed before this step like I did, it’s recommended in the Microsoft documentation to uninstall first to prevent any unexpected or unwanted interactions with new installs through nvm. The resource provided by the Microsoft documentation to remove node.js from Windows can be found here.

  • However, this resource may be out of date. Instead, I found the steps to uninstall node and npm at the bottom of this article clearer and still effective. You should also remove any system environment variables that point to node or npm.

  • After node and npm are uninstalled, open the Ubuntu command line to install cURL with sudo apt-get install curl

  • Then use cURL to install nvm with curl -o- | bash

Note: At the time of writing, the most recent version of nvm is v0.35.3, but you can find the most recent version in their GitHub repo here.Just replace v0.35.2 in the above code with your desired version.

  • Optional: At this point, I installed build essentials and python as these are required in many npm libraries. To do this, enter sudo apt install build-essential python -y

  • Close and reopen the Ubuntu terminal for the install to take effect.

  • You can verify the install with command -v nvm which should return nvm

  • nvm ls will display currently installed versions of node, which should be N/A at this point.

  • Next, install the latest stable LTS version of nodejs with nvm install --lts

  • Another check with nvm ls should now display the latest stable releases as your default as seen below.

  • You can also check the versions of node and npm, along with their default paths with node --version, npm --version, which node, and which npm as seen below.


Step 5: Install Truffle and test your contracts

  • Now just enter npm install -g truffle to install Truffle. Or, to also install the Ganache client enter npm install -g truffle ganache-cli

  • You can test that Truffle was installed by following the steps at the end of this article.

  • Alternatively, or additionally, you can enter one of your own projects and run truffle compile to make sure your contracts compile properly.


1 Like

Hi @Jshanks21,

Thanks for creating this guide :pray:

I had issues installing nvm as I had errors that it required npm, so assume this was the issue of already having node/npm installed. I installed node and then installed nvm.

WSL2 will be generally available in the next version of Windows 10 (2004) so hopefully not too far away:

1 Like

Hi @abcoathup,

No worries! Glad to do it.

All the sources I found suggested removing any trace of node/npm on your computer before installing nvm to avoid unexpected issues. This also includes removing any system variables with a path leading to node/npm files.

The error seems to suggest that something is expecting npm to handle the install instead of cURL. A leftover system variable pointing to npm is my first guess.

Were you running the install through the Linux terminal?

After fully uninstalling node/npm, you’d want to use the Linux terminal, Ubuntu in the case above, to install cURL with sudo apt-get install curl.

Then use cURL through the Linux terminal to install nvm with the command curl -o- | bash.

Once installed, close and reopen the terminal for effects to take place and you can use nvm to install nodejs (which should include npm) with nvm install --lts.

It can be a bit tedious initially, but so far I’ve noticed much smoother performance working with my projects than on Windows directly (shocking, I know). Looking forward to version 2004! I’m not used to manually updating my tools. :sweat_smile:

1 Like

Yes. I ran it via an Ubuntu terminal. I assume I still have npm in my path when I ran curl

I am finding WSL2 much faster than WSL. I had been going to wait for general release, but given that we are now close, decided to give it a go.

1 Like

Glad to know there’s a noticeable difference. Have you noticed any buggy behavior with it? That’s the only reason I didn’t go with WSL2. I guess if it’s close to release any bugs should be limited though.

1 Like

No obvious bugs so far, though it is early days. I like the speed of WSL2.

1 Like

I store my git credentials in Windows Credential Manager.
I previously created a GitHub Personal Access Token.

1 Like

Seems easy to implement. But I’ve been using VSCode and I’m able to commit and push all changes within the editor. What are the benefits of storing git credentials in WSL if I’ve grown accustomed to doing it this way?

Btw, I am familiar with using git bash, or other terminals, to stage, commit, and push changes, so I do understand how to do this traditionally. But VSC has just proven to be too convenient not to use more often for my own projects.