Windows Subsystem for Linux Setup

Hey everyone :wave:

Windows Dev and setup for RedwoodJS is more challenging than macOS or Linux because is don’t work out of the box. You need a shell to run Node.JS and you got a tone of it, like git-bash or PowerShell.

However, I really believe that Windows Subsystem for Linux is the TheBest™ Windows setup.

If you don’t believe me, here citation from Microsoft itself :wink: :

When working with JavaScript-based frameworks in a professional capacity, we recommend WSL as it currently supports better performance speed, system call compatibility, and alignment between your local development environment and deployment environment (which is often a Linux server). WSL enables you to leverage Linux workspaces and avoid having to maintain both Linux and Windows build scripts. Running Docker containers is often a better experience via WSL as well. Specifically, WSL 2 (the updated version) will typically work best with JavaScript frameworks.

I’m totally open to conversations, and it’s also okay to have personal preference.
The goal here is to have something that works for everyone, easily, without Windows specific bugs.

Before we start I want to answer to these concerns of using WSL2 from the last topic

The 2 first points is caused by the dynamic memory allocation of WSL, in the last beta update of Windows, the memory allocation should be better, but it will always be more demanding when you run 2 system at the same time. My recommendation is to have at least 16Gb of memory to work on a Redwood project and 32Gb when you work on the framework. I know is a lot, but it’s the only way to have a smooth experience on WSL because at the end is virtualisation. Tip : if you want to work a something more lite, I suggest making a dual boot with Ubuntu to have a lean system, you can follow every of this doc except installing WSL.

The last point is solved since the new Redwood extension (redwood-kaimana) is now working with WSL2.

So now let’s start this setup process!

Developing Redwood Projects on Windows

Install WSL*


You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.
In some cases, you need to enable virtualisation on your BIOS.


You can install everything you need to run Windows Subsystem for Linux (WSL) by entering this command in PowerShell or Windows Command Prompt and then restarting your machine.

wsl --install

This command will enable the required optional components, download the latest Linux kernel, set WSL 2 as your default, and install a Linux distribution for you (Ubuntu by default).

The first time you launch a newly installed Linux distribution, a console window will open, and you’ll be asked to wait for files to decompress and be stored on your machine. All future launches should take less than a second.

Set up your Linux user info

Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution

Set up Windows Terminal (optional)

You can Install Windows Terminal, is really nice open-source app to manage all of your shells. But most of the time, the VSCode Terminal is the way to go.

Install nvm, node.js, npm, yarn, and PostgreSQL

  1. Open your Ubuntu command line.

  2. Update your packages: sudo apt update

  3. Install cURL with: sudo apt-get install curl

  4. Install nvm, with: curl -o- | bash

  5. To verify installation, enter: command -v nvm …this should return ‘nvm’, if you receive ‘command not found’ or no response at all, close your current terminal, reopen it, and try again. Learn more in the nvm GitHub repo.

  6. List which versions of Node are currently installed (should be none at this point): nvm ls

  7. Install the latest stable LTS release of Node.js : nvm install --lts

  8. List what versions of Node are installed: nvm ls …now you should see the two versions that you just installed listed.

  9. Verify that Node.js is installed and the current default version with: node --version. Then verify that you have npm as well, with: npm --version (You can also use which node or which npm to see the path used for the default versions).

  10. Install Yarn with: sudo apt install yarn

  11. Confirm installation: yarn --version

  12. Install PostgreSQL with: sudo apt install postgresql

  13. Confirm installation: psql --version

If you have problems with yarn you should probably remove cmdtest and install Yarn again :
sudo apt remove cmdtest

Install VSCode

To install VS Code and the Remote-WSL Extension:

  1. Download and install VS Code for Windows. VS Code is also available for Linux, but Windows Subsystem for Linux does not support GUI apps, so we need to install it on Windows. Not to worry, you’ll still be able to integrate with your Linux command line and tools using the Remote - WSL Extension.

  2. Install the Remote - WSL Extension on VS Code. This allows you to use WSL as your integrated development environment and will handle compatibility and patching for you. Learn more.

Other code editors, like IntelliJ, Sublime Text, Brackets, etc. will also work with a WSL 2 Node.js development environment, but may not have the same sort of remote features that VS Code offers.

Ready to Redwood

At this point we should be able to run this command on your favourite terminal who run bash on Ubuntu:

yarn create redwood-app my-redwood-app

When they wrote this could take a while, this really take a while the first time, don’t worry.

After you see : Fire it up! :rocket:, it’s time to have fun!

So go to your new project with : cd my-redwood-app

And if you are not already on VScode, here’s a trick : code .
That will open VScode with your project on WSL automatically.

You can now start your dev server with : yarn rw dev
Another WSL magic trick, your project will open on your favourite Windows browser (Microsoft Edge, right?).

Set up your local database

Database is always to most tricky part and is not easier on Linux, so I made a quick setup for PostgreSQL.

Enter inside Postgres user as admin with :

su - postgres

and create databases for your project :

createdb projectname

createdb projectname_test

You also need to create a password for the database user

type psql to enter inside the database and write this query

ALTER USER postgres PASSWORD 'mypassword';

Inside your project edit the .env file with these 2 new lines



Use this command to start the DB server

sudo service postgresql start

and restart your dev server

That’s it !

*This work is a derivative of “windows-uwp” by Microsoft Docs, used under CC BY 4.0.


Q : Why I see an error like Watchpack Error (initial scan): Error: EACCES: permission denied, lstat '/mnt/c/swapfile.sys'
A : You can use Ubuntu inside a Windows folder, but that will always cause permissions error. Before you use CRWA or git clone, check if your folder path start with a “~” or go to it with cd ~.

Q : Can I use WSL for RedwoodJS framework contribution ?
A : Yes, every script should work on WSL and rwfw also work well

I wish this doc can help people to get start with RedwoodJS on WSL. If you have questions or see mistakes, I will be happy to answer ! :grin:


This is awesome!

1 Like

New Windows Setup Cookbook

Thanks to @simoncrypta there’s now an official Redwood Cookbook. Check it out over here:

Thanks, Simon! :rocket:


Simon, great job on describing the (murky) waters of using Windows Subsystem for Linux for RedwoodJS development on Windows. I spent a good amount of time trying to write an alternative version on RedwoodJS application development on Windows - and missed addressing the RedwoodJS framework development which requires using the Windows Subsystem for Linux, because of all scripts used in the framework development.

My current proposal - Testing and Debugging Project is dedicated to Redwood application developers so I am skipping WSL 2 use completely and using VSCode to handle all of the platform (MacOS, Linux and Windows) specific issues.


Hi @adriatic (btw, nice name :wink: )

I don’t know if anyone mentioned before but, there is a known issue with WSL2 performance when handling files from mounted ‘windows partition’ (basically, what you access when open VSC with ubuntu terminal). WSL1 works quite ok (I’m using it currently without issues). If you really need WSL2 you always have a option to use both 1&2 versions at same host. (if you need more details, feel free to reach me on discord)

1 Like

Thanks for your message Mr. Bubrić. My pseudonim comes from my Croatian past (left to go to California in 1982) when I used to spend each summer on the Adriatic coast.

My intent is to fold Windows Subsystem for Linux Setup thread (at least some parts of it) to this website, created to engage community members to write technical rw documentation, from the view-point of an app developer (as different from the core team’s prospective.

Since I am already conversing with you - please check this discussion as well as today’s status update. If possible, please do provide your feedback

1 Like

In case anyone is facing performance issues inside WSL2, using the Linux system root for projects should provide much better performance than using a Windows directory

As from the Microsoft docs:

For example, when storing your WSL project files:

  • Use the Linux file system root directory: \\wsl$\<DistroName>\home\<UserName>\Project
  • Not the Windows file system root directory: C:\Users\<UserName>\Project or /mnt/c/Users/<UserName>/Project$