Development with Nitro and WSL2
Nitro requires WSL2 for Windows, which runs the Linux distribution of your choice inside your normal Windows operating system. Nitro uses Docker in this environment to manage containers, which comes with limitations and performance considerations.
# Mind Your Terminal
We recommend using Windows Terminal (opens new window), Microsoft’s new(ish), free app that provides easy access to the various Windows shells.
Windows Terminal opens PowerShell by default, which you’ll need for first installing WSL2, and the Ubuntu shell you’ll want for installing and using Nitro. You’d otherwise need to run “PowerShell” or “Ubuntu” separately from the Start menu.
# Filesystem Performance is Best Inside WSL2
Running WSL2 means you have two filesystems: the Windows one you’re used to, where your home directory looks like
C:\Users\Oli, and the Linux one where the home directory is something like
Each filesystem has a reference to the other: a
\\wsl$ share is available to Windows and a
/mnt folder exists in the Linux filesystem. (So from the Ubuntu terminal, your Windows
C:\Users\Oli folder is available at
Using the Linux mount incurs a performance penalty, so it’s best to keep your project files in the Linux volume only. Your Ubuntu home folder is an ideal place for projects, i.e.
/home/oli/dev which is equivalent to
~/dev. As long as the full path to your project folder does not start with
/mnt, you’ll get optimal performance from Nitro and Docker.
This also means working with your files from Windows is less convenient, but you can access the Linux filesystem from Windows by accessing the
\\wsl$ in the File Explorer’s address bar and press Enter. You should see an “Ubuntu-20.04” share volume available to browse.
If you use PhpStorm, you can load your project via
\\wsl$\Ubuntu-20.04\home\oli\dev\mysite.nitro. Performance isn’t as fast as the native filesystem, but faster than going through
# Set Permissions When Adding a New Site
When adding a new site, you’ll need to manually set permissions from the root of the Craft project from within the WSL2 distro:
chmod 777 ./.env chmod 777 ./composer.lock chmod 777 ./composer.json sudo chmod -R 777 ./config sudo chmod -R 777 ./storage sudo chmod -R 777 ./vendor sudo chmod -R 777 ./web
You’ll probably need those
sudo commands to properly set permissions on directories. You can try first without them, but a
chmod(): Operation not permitted warning from Craft means you’ll need those elevated permissions.
# Manually Trust Certificates and Edit the Hosts File
The first time you add a Craft site, you’ll need to manually run a command on the Windows host machine to import a certificate file so SSL will work. You can follow the terminal output for exact instructions.
Nitro cannot edit the Windows hosts file at
C:\Windows\system32\drivers\etc\hosts and will provide you with copy+paste instructions when it needs the file updated. It’ll look something like this:
For your hostnames to work, add the following to `C:\Windows\System32\Drivers\etc\hosts`: ---- COPY BELOW ---- # <nitro> 127.0.0.1 mysql-8.0-3306.database.nitro mysite.nitro myothersite.nitro # </nitro> ---- COPY ABOVE ----
Nitro attempts to update hostnames when you run
nitro apply—so you may need to run that after adding your first site.
Windows only allows for up to nine aliases per line in the hosts file. If you have more than nine, you will need to add any aliases after the ninth one onto a new line below starting with
# Note WSL2 Memory Usage
WSL2 has been known to consume a lot of memory, most noticeably on machines with more limited RAM.
If you find WSL2 consuming more of your system memory than you’d like, you can manually specify limits by adding a
.wslconfig to your user directory.
If we wanted to limit WSL2 to 6GB memory, for example, we would create a
C:\Users\Oli\.wslconfig file with the following contents:
[wsl2] memory=6GB swap=0
wsl --shutdown and restart Docker to apply the change. This will put a hard limit on RAM usage and prevent any swap file from being created.
On the other hand, if your database containers are unexpectedly stopping or the
vmmem.exe process heavily consumes disk usage for several minutes, you probably don’t have enough memory or swap file allocated to WSL2.