Can I Create a Linux/MacOS-like Ethereum Developer Setup on Windows?: A Guide to Setting up Windows Subsystem for Linux

Step by step instructions on how to utilize WSL 2 to setup your Ethereum smart contract development environment and workflow
by Thomas HayNovember 18, 2020

At ConsenSys Academy, we asked everyone in the Developer Program to download a Virtual Box and Ubuntu at the start. Our goal is that every student can have a consistent user experience when setting up their local development environment. No matter their native operating system (OS), everyone would have Ubuntu and be able to run the same software. This is a good idea in theory. In practice, we have worked with students to deal with issues related to the available memory on their machine in order to make this work. Almost always, Mac users will proceed without downloading Ubuntu, due to MacOS being a Unix-based system. Windows users are often frustrated, as they were not able to use the development tools following the instructions we recommend on their native OS, and if they wanted to run everything on Windows they had to follow along with a set of instructions parallel to those for Linux and MacOS users. 

We had been monitoring the development of Windows Subsystem for Linux (WSL). The launch of WSL 2 coincided with questions from our current cohort of Bootcamp students about whether they could use WSL 2 instead of downloading a Virtual Box. I felt it was past time to provide greater focus on how to use WSL 2 to provide Windows users a Linux-like developer experience while using the Ethereum tooling that we recommend. This article will share with you some idiosyncrasies we encountered in using WSL 2 to set up your Ethereum developer environment (like what you have to do in order to utilize truffle commands). 

Our ecosystem has many helpful articles and tutorials out there, but people create them assuming the user has Linux or MacOS installed. I want Ethereum to be accessible to everyone, and wanted to share what I believe is currently the easiest way for developers who use Windows to set up their development environment so they can follow along with the majority of articles published on developing smart contracts.

You can jump into the tutorial below, or skip ahead to a short history on why Linux and MacOS users traditionally had an easier path to developer tooling in Ethereum.

Using WSL 2 to Setup Your Ethereum Developer Environment

Step 1: Downloading WSL 2

TLDR; Windows does a really good job of walking you through the instructions of how to install WSL 2 to your machine. “Windows Subsystem for Linux Installation Guide for Windows 10” is a comprehensive article because it both lives up to the title, as well as provides troubleshooting tips. We also found that watching starting at 8:24 of WSL2: Code faster on the Windows Subsystem for Linux! | Tabs vs Spaces video gives some additional context around how to enable WSL via graphical user interface (GUI) instead of via command line (or PowerShell). You may have to restart your computer multiple times, and in some cases, depending on the hardware your machine has, this might take some time. I would be ready to put aside half a day as a worst-case scenario, just to manage your expectations for all the installations you are about to do.

In step 6 of the aforementioned article, I chose to install Ubuntu 20.04 LTS, as I was most comfortable with this distribution versus the others listed. I tried to install Ubuntu via the provided link to the Windows store, accessed via my web browser, but my windows machine then prompted me to install using the built-in Microsoft Store Application.

I also installed Windows Terminal, which was optional. I did this after making a bunch of mistakes you will see in Step 3. Instead of continuing to “go my own way”, I decided to follow along with what Microsoft was telling me. The advantage of Windows Terminal is that in a terminal window, you can open multiple terminal tabs of different operating systems.

Step 2: Running WSL 2 alongside VSCode

We suggest that you use whatever IDE you are most comfortable with. Personally, I use VSCode, so I wanted to figure out how I could use VSCode alongside WSL 2. I already have VSCode installed, so if you do not have it installed, go ahead and install it. Then, in order to get it running alongside Ubuntu, I found the answer at 5:31 of a video on WSL created by microsoft.

Using the command:

code . 

automatically downloaded, installed, and started up VSCode, but I did find that my extensions that I use to write smart contracts are not automatically installed.

Simply clicking on the green text installed in WSL:Ubuntu. VSCode also prompted me to install some additional libraries via the terminal within VSCode, and asked me to enter my password for my Linux distribution (which is Ubuntu 20.04 LTS)

There is a longer tutorial called Get started using Visual Studio Code for Windows Subsystem for Linux that provides a longer walkthrough if you have not yet installed VSCode. From this point forward, I did all the following steps inside of the terminal of VSCode, which was now set up as a bash shell.

Step 3. Install nvm, Node and npm

Before installing developer tools like Truffle, we need to install nvm, Node, and npm. Refer directly to the article Set up your NodeJS development with WSL 2.  

The first idiosyncrasy that I ran into was the documentation did not have the most up to date version of nvm listed, and therefore I recommend to go to the nvm GitHub repository to find out the current release. After installing nvm, when I ran the command command -v nvm to confirm it was installed in my terminal, nothing happened (nvm should be returned). It suggested that I close my terminal and reopen it, then run the command again. When I did this, I got nvm.

Then, I typed in nvm install node –lts I opted for the LTS (long-term stable) release. After checking that I had both node and npm installed (node –version , npm –version). I moved onto the next step. 

Do not do the following

This is a clear example of not reading the documentation (always read the documentation). The steps I detailed above I did after first going down the path of not reading the docs all the way through. Chronologically,  I first opened the terminal with VSCode and typed in

node -v

to see if I had it installed. Since I did not have node installed, the following returned:

I typed in the suggested

sudo apt install nodejs

and was prompted for my password.for my linux distribution (Ubuntu 20.04 LTS). I then typed in

node -v

The version that returned was 10.19.0. I looked at the Node.js website and the recommended stable release was 14.15.0 LTS. Not what I wanted to happen. Additionally, when I typed in

npm -v

to see if I had NPM installed, I got back bad interpreter: No such file or directory. What went wrong? If I just started by reading the article, I would have seen the following

“the version of Node that can be installed with Ubuntu’s apt-get command is currently outdated”

If you found yourself having gone down this path, you need to uninstall Nodejs – here are some helpful instructions, but you will use the command

sudo apt-get purge nodejs

within the terminal to do so.

If you navigate directly to the Node.js website and download and install, you will install the Windows distribution, which you will not be able to use in Ubuntu. So read the above documentation first, and do not try to just “jump in:.

Learn from my mistakes and save yourself time. Read the documentation.

Step 4. Install the Truffle Suite

At this point, I could now follow along with the steps described on the ConsenSys Developer Portal.

Be sure to uncomment the development network (as seen below) in the truffle-config.js file

If you do not, you will get the following error:

Wait…I set it all up and there was an error, I walked away, and now that I have it running, I’ve forgotten my password to my linux distribution!!!

Ahh, yes. I too have done this. I found the article “Create a user account and password for your new Linux distribution” very helpful. 

Things I installed in Windows are not showing up when I run Ubuntu! What gives!!

Remember, Ubuntu is a different operating system than Windows. Programs installed on Windows are not expected to instantly run Ubuntu distribution and vice versa, unless they are specific programs configured to do so – Windows Terminal being an example. Assume that anything you install on one will not work on the other to be safe.

What next?

Now follow along with Step 2: Create a Smart Contract and Step 3: Launch a Decentralized Application using the same commands as these tutorials provide.

A Brief History of Operating Systems and the Context for Ethereum Developers

Why is it that Windows users have a different experience with Ethereum developer tooling than those who use Linux or MacOS? Linux and MacOS are not the same operating system, and there are countless Linux distributions. It seems like there would have to be multiple sets of tooling to deal with the various operating systems out there. To answer this question requires a brief history lesson. I recommend watching Crash Course’s Video Operating Systems: Crash Course Computer Science #18 for some concise background information. 

Our story picks up with Unix. After the release of Unix in 1969, this operating system quickly established itself within the computing community. Computing was very much dominated by the research, large business, or hobbyist/hacker communities during the 1970’s, and did not have the graphical user interfaces we are accustomed to today. Unix was terminal-based at this time, so everything was done via what we would call the command line.

The 1980’s coincided with Microsoft and Apple releasing popular operating systems for the personal computing audience. The advancements that these operating systems brought, alongside a decrease in the cost of hardware and memory, helped grow the number of people outside of academia or the business world able to afford a computer for personal use. Microsoft released Microsoft Disk Operating System (MS-DOS) in 1981. When Microsoft Windows was released in 1985, this graphical user interface-based operating system was built on top of the MS-DOS code base, making the computer much more accessible to the end user.

Apple actually allowed the booting of multiple OSes on the Apple II, which first started selling in the late 1970s. But Apple, prior to Microsoft, realized how important a GUI would be to driving adoption of the personal computer. Apple’s first GUI-based OS, the Macintosh Operating System (now called Classic MacOS) originated from the Apple Lisa (LisaOS), a computer released in 1983. The operating system on the Lisa was heavily inspired by work done at Xerox’s Palo Alto Research Center (PARC), and many on the Xerox PARC team worked at Apple. When the much more popular Apple Macintosh was released in 1984, Classic MacOS was running on it. When looking at old pictures and videos of the Macintosh, I was surprised at just how familiar an interface that Classic MacOS is to the MacOS running on my Apple computer today.

Unix had been the dominant operating system in the computing world, and it continued to be popular outside of the personal computing space in the 1980s. During the 1980s that meant that there were three different operating systems built on three different codebases. Using a program across these operating systems could not happen natively. The programs had to be modified to work with the OS. The GUI-based operating systems of Apple and Microsoft made computing accessible to the masses. For developers, building an application that could work on a computer required knowing the operating system (and it still does). But Apple would make choices that would make it easier for developers familiar with Unix commands to use MacOS or a Unix-based operating system less of a barrier of entry.

Apple began making moves toward a Unix-based operating system, starting in 1988, when the Unix-based A/UX was released. On a parallel track, NeXT, co-founded by Steve Jobs in 1985 upon his departure from Apple, was creating a Unix-based OS called NeXTSTEP. Apple purchased NeXT in 1996, and acquired the intellectual property that would become MacOS X. To recap, Apple’s co-founder left the company, co-founded another computer company to build computers and operating systems, which was then purchased by the company he first co-founded, which he subsequently became CEO of, and then took a project from his new company, and that software project was built to become the basis of the MacOS I’m running on my Apple computer right now. In Steve Jobs by Walter Issacson, there is a quote from Larry Ellison, co-founder of Oracle, about a conversation he had with Steve Jobs while they were on vacation in Hawaii.

“You know Larry, I think I’ve found a way for me to get back into Apple and get control of it without you having to buy it,” Jobs said as they walked along the shore. Ellison recalled, “He explained his strategy, which was getting Apple to buy NeXT, then he would go on the board and be one step away from being CEO.”

Isaacson, Walter. Steve Jobs. New York ; Toronto: Simon & Schuster, 2011. p.300

So that is how MacOS became a Unix-based operating system, and made it possible for Unix command to run on the terminal in MacOS.

Windows did not become Unix-like. After the major success of Windows 95/98, Windows made the shift to building its OS off of NT (the acronym NT no longer stands for anything, but there are many theories and histories around the choices of NT – a fun rabbit hole to go down if you are interested in Microsoft history). Starting with Windows 2000, Microsoft deprecated the dependence on DOS (leading to this incredible video of Bill Gates turning off DOS when Windows XP was released). Windows has continued to be based off of NT for all subsequent releases, including Windows 10.

Between Apple and Microsoft, a third competitor would emerge. Linux was developed and released by Linus Torvalds in 1991. It is a Unix-like operating system, and due to being both free and easily customizable, and it was quickly adopted by developer communities that did not want to be locked in to Apple or Microsoft. Linux continued to gain popularity and it found itself being used in many different computing environments. For example, Android, which is a mobile operating system, is built on Linux, and is the most popular smartphone operating system. Linux also maintained the Unix shell commands. For more information on Linux, Running Linux, Third Edition is a comprehensive resource.

Being based off of Unix has meant that commands written in the MacOS terminal and a Linux terminal are syntactically the same because they both use the bash shell (or some derivative of it like zsh). Windows users often have to translate a command they see in a tutorial written for the bash shell to work in Windows PowerShell or Cmd. Linux or MacOS users can just run the command. Developers spend a ton of time in the terminal. This has meant installing and using certain developer tooling for Ethereum (and many other languages), like nvm, Node, npm, and Truffle has required a different set of instructions for Windows users. 

The result is that there is greater compatibility between Linux and MacOS – and thus why many of the commands used in Ubuntu terminal, a Linux distribution, can also be used (largely) interchangeably in the MacOS terminal. Windows has forayed into Unix-based OS in the past, but the release of WSL in 2016 for Windows 10 was the first time that Windows users could use a Linux Kernel while simultaneously using Windows without a virtual machine. WSL 2 has created a lightweight virtual machine that runs inside Windows, meaning that a developer no longer has to deal with the memory and storage issues related to downloading a virtual box or using VMWare to install Ubuntu.

Why does this impact Ethereum developers? Ethereum’s Genesis Block occurred on July 30, 2015, and according to Ethereum co-founder  and founder of ConsenSys Joe Lubin, most of the development was happening on Ubuntu and MacOS X. Therefore, it is not surprising that much of the original tooling worked well with Unix-like operating systems. While there has been tooling developed specifically for Windows, oftentimes the experience for developers is better when they can use a Unix-like terminal to install software and run commands. 

Microsoft put in the work to get WSL 2 out and it has improved to where many within the community have been using it since late 2018 to install a Linux distribution. If you use Windows, you no longer have the pain of having to follow a slightly modified set of instructions when building your dApp. Windows users can now follow along with Ethereum tutorials for Linux or Mac.

A highly entertaining read, recommended to me by Avery Erwin, is Neal Stephenson’s “In the Beginning was the Command Line”, an essay/book on his personal experience with operating systems during the time period described in this short history.


This tutorial and brief history gives a Windows user some insight into how to set up their development environment using WSL 2, Ubuntu, VSCode, npx, Node, npm, and Truffle. It also gives a bit of the history of how and why we must do this. If you have any comments or helpful hints based on your experience, please send them to [email protected] so I can update this article and credit you for your contribution.

Special thanks to Onyebuchi Valentine Ahiwe, Clemens Wan, Anthony Albertorio, Eli Geschwind, Nick Nelson and more kind friends for your review and comments on this tutorial and history. I appreciate your comments.