Set up freeCodeCamp on Windows Subsystem for Linux (WSL)

This guide covers some common steps with the setup of WSL2.

Once some of the common issues with WSL2 are addressed, you should be able to follow this local setup guide to work with freeCodeCamp on Windows running a WSL distro like Ubuntu.

System Requirements

Hardware:
- A fast CPU (6+ cores)
- At least 12+ GB RAM
- 20+ GB of free disk space
- (Optional) 30-50 Mbps internet connection
Operating System: Windows 10 64-bit (Version 2004, Build 19041 or higher).
Docker Desktop for Windows: See the requirements for Windows.

Enable WSL

Follow the instructions on the official documentation to install WSL2.

Install Ubuntu

We recommend using Ubuntu-22.04 or above with WSL2.

As of November 2023, Ubuntu and Debian are the only Linux distributions officially supported by Playwright, the end-to-end testing library used by freeCodeCamp.

You may use other non-Debian-based distributions, they all come with their own ‘gotchas’ that are beyond the scope of this guide.

Here is how you can run a linux flavour of your choice

Update the dependencies for the OS

sudo apt update
sudo apt upgrade -y

# cleanup
sudo apt autoremove -y

Set up Git

Git comes pre-installed with Ubuntu 22.04, verify your Git version with git --version.

~
❯ git --version
git version 2.25.1

(Optional but recommended) You can now proceed to setting up your ssh keys with GitHub.

Installing a Code Editor

We recommend installing Visual Studio Code. It has great support for WSL and automatically installs all the necessary extensions on your WSL distribution.

Essentially, you will edit and store your code on Ubuntu-22.04 with VS Code installed on Windows.

Installing Docker Desktop

Docker Desktop for Windows allows you to install and run databases like MongoDB and other services like NGINX and more. This is useful to avoid common pitfalls with installing MongoDB or other services directly on Windows or WSL2.

Follow the instructions on the official documentation and install Docker Desktop for your Windows distribution.

Configure Docker Desktop for WSL

Once Docker Desktop is installed, follow these instructions and configure it to use the Ubuntu-22.04 installation as a backend.

This makes it so that the containers run on the WSL side instead of running on Windows. You will be able to access the services over http://localhost on both Windows and Ubuntu.

Installing Node.js and pnpm

We recommend you install the LTS release for Node.js with node version manager - nvm. Once installed use this command to install and use the latest Node.js LTS version:

nvm install --lts

For instructions on installing and using a different version of Node.js, please refer to the nvm docs.

Node.js comes bundled with npm, which you can use to install pnpm:

npm install -g pnpm

Set up freeCodeCamp Locally

Now that you have installed the pre-requisites, follow our local setup guide to clone, install and set up freeCodeCamp locally on your machine.

Optimize memory allocation

The default settings for your WSL installtion can vary, we recommend tuning the memory allocated to WSL by Windows by following these steps.

Create a .wslconfig file in your %UserProfile% directory, typically at C:\Users\<UserName>\.wslconfig. Replace x with values that suit your own needs:

# Settings apply across all Linux distros running on WSL 2
[wsl2]
# Memory to assign to the WSL 2 VMs.
memory=xGB
# Swap space (on disk) for the WSL 2 VMs, default is 25% of available RAM
swap=xGB

You can read more about the config in the official guide here.

Troubleshooting

Here are some useful links:

Official FAQ for Windows Subsystem for Linux.
Official FAQ for Docker Desktop for Windows.
Getting help from our community.