Skip to content
Avaloi

Local development on Windows with WSL2

Run an Avaloi site on a Windows computer with DDEV through WSL2 and Ubuntu: install it, trust the local https certificate, free ports 80 and 443, keep the project in the right place, and edit with VS Code.

Parts of this feature are still being built. The Not yet section lists them.

DDEV runs best on Windows through WSL2, which is a real Linux (Ubuntu) inside Windows. The Avaloi add-on supports only that way. DDEV on plain Windows (PowerShell, Git Bash, or Docker Desktop with the project on C:\) is not supported by the add-on. WSL2 is free, built into Windows 10 and 11, and quicker for WordPress than the Windows file system.

The local site opens over https only, at https://NAME.ddev.site, with no port number. A Windows browser trusts that address after one step, which the setup does for you and which is explained below.

The short way

  1. On the Info tab of your site, in the Local development card, click Download starter.

  2. Unzip it into any folder, for example Downloads.

  3. Open PowerShell in that folder and run:

    powershell -ExecutionPolicy Bypass -File .\setup.ps1

    Windows blocks downloaded scripts by default. That line allows this one run only.

setup.ps1 checks for WSL2 and Ubuntu and tells you how to get them if they are missing. It installs nothing itself. Then it runs setup.sh inside Ubuntu. That script copies the project into your Linux home folder (after asking), checks Docker and DDEV, installs the Avaloi add-on, and runs ddev avaloi setup. Setup asks before each change: it frees ports 80 and 443, makes Windows trust the DDEV certificate, asks for your API key, links the site, and pulls the code, database, and uploads. At the end it prints the address and a local admin login.

The rest of this page explains each part, in case a step needs your help.

1. Install WSL2 and Ubuntu

Open PowerShell as administrator and run:

wsl --install -d Ubuntu

Restart if Windows asks. Open Ubuntu from the Start menu once. It asks you to choose a Linux user name and password. That finishes the install.

Check that it is WSL2 (the last column says 2):

wsl -l -v

If it says 1, run wsl --set-version Ubuntu 2.

2. Docker: Engine in Ubuntu or Docker Desktop

DDEV needs Docker. Pick one.

Docker Engine inside Ubuntu Docker Desktop for Windows
Cost Free Free for personal use and small companies, paid for larger ones
Speed with the project in ~/projects Fastest Fast
Setup Install in Ubuntu: docs.docker.com/engine/install/ubuntu Install on Windows, then turn on Settings, Resources, WSL integration for Ubuntu
Tested with this add-on Yes (Docker Engine 29 on Ubuntu 24.04) Not yet

Also install DDEV inside Ubuntu, not on Windows: DDEV for WSL2. It includes mkcert, which makes the local https certificate.

If containers cannot reach the internet or resolve names with Docker Engine in WSL2, put {"dns": ["1.1.1.1", "8.8.8.8"]} in /etc/docker/daemon.json and restart Docker (sudo service docker restart).

Give Docker at least 4 GB of memory. With Docker Engine that is the memory of the WSL2 machine: create %UserProfile%\.wslconfig with:

[wsl2]
memory=6GB

then run wsl --shutdown and open Ubuntu again.

3. Where to keep the project

Keep it in the Linux home folder, for example ~/projects/my-site. Never under /mnt/c/... (that is your C:\ drive seen from Linux). WordPress is many small files, and the Windows drive is slow for them. File permissions also break there, and Git shows every file as changed.

setup.sh and ddev avaloi doctor warn when the project is on a Windows drive. setup.sh offers to copy it into ~/projects for you.

4. Edit the files

You edit from Windows, and the files stay in Linux.

  • VS Code: install the WSL extension (called Remote - WSL). In Ubuntu, go to the project and run code .. VS Code opens in Windows and works on the Linux files. Its terminal is the Ubuntu shell, so ddev and git just work.
  • Windows File Explorer: in Ubuntu, run explorer.exe . in the project folder. You can also type \\wsl.localhost\Ubuntu\home\YOUR-USER\projects in the Explorer address bar.
  • Other editors can open the same \\wsl.localhost\... path. Editing works. Running git or ddev from Windows tools on that path is slow, so run them in Ubuntu.

Open the site in a Windows browser at https://NAME.ddev.site. WSL2 forwards localhost to Windows by itself.

Line endings

Windows editors can save files with Windows line endings (CRLF). A shell script with CRLF fails with bad interpreter or $'\r': command not found. Tell Git, inside Ubuntu, to keep Linux endings:

git config --global core.autocrlf input

In VS Code, set Files: Eol to \n, or click CRLF in the status bar and choose LF. A committed .gitattributes with * text=auto eol=lf fixes it for the whole team.

5. The certificate: "Your connection is not private"

DDEV makes its own certificate authority with mkcert, inside Ubuntu. Windows does not know it, so Chrome and Edge show Your connection is not private, and WordPress shows mixed content warnings. The fix is to tell Windows to trust that authority. Run this in Ubuntu:

ddev avaloi trust

It does two things, and asks before each:

  1. Runs mkcert -install in Ubuntu, so programs in Ubuntu trust it.
  2. Adds the public certificate (rootCA.pem, never the key) to your Windows user's Trusted Root Certification Authorities, with PowerShell's Import-Certificate into Cert:\CurrentUser\Root. That needs no administrator. Windows shows a Security Warning window: choose Yes.

It checks the certificate's thumbprint first, so running it twice does nothing the second time. Afterwards, close every browser window and open it again. Firefox keeps its own list: open about:config and set security.enterprise_roots.enabled to true.

Check the state any time with ddev avaloi trust --check or ddev avaloi doctor.

By hand

If the command cannot reach Windows, do it yourself. In Ubuntu, find the folder:

mkcert -CAROOT

Then open Windows PowerShell (not Ubuntu) and run, with the folder's Windows path (for a path under /mnt/c/Users/you/... that is C:\Users\you\...; for a path in Ubuntu it starts with \\wsl.localhost\Ubuntu\):

Import-Certificate -FilePath "C:\Users\you\AppData\Local\mkcert\rootCA.pem" -CertStoreLocation Cert:\CurrentUser\Root

ddev avaloi trust prints the exact line for your computer.

"Exec format error" when Ubuntu starts powershell.exe

WSL can lose the ability to start Windows programs when systemd is on. Then ddev avaloi trust says it cannot reach Windows. In Ubuntu run:

sudo sh -c 'echo :WSLInterop:M::MZ::/init:PF > /proc/sys/fs/binfmt_misc/register'

or run wsl --shutdown in PowerShell and open Ubuntu again.

6. Ports 80 and 443

DDEV serves the site on the normal web ports, so the address has no port number. If another program holds port 80 or 443, DDEV cannot, and ddev avaloi doctor tells you which program and how to stop it. Common ones:

What holds the port How to free it
apache2 or nginx running in Ubuntu sudo systemctl disable --now apache2 (or nginx)
Another Docker project docker ps, then docker stop NAME, or stop that stack
IIS or the World Wide Web Publishing service on Windows (shows as System) In an administrator PowerShell: Stop-Service W3SVC, then Set-Service W3SVC -StartupType Disabled
Skype, or another program on Windows Quit it
wslrelay It forwards a WSL program's port. Find the program in Ubuntu, or run wsl --shutdown

If you truly cannot free the ports, ddev avaloi doctor --fix --custom-ports picks other ports (33000 and 33001, for example). That is a last resort: the address then carries the port, such as https://NAME.ddev.site:33001, and so does the site address stored in the database. Free the ports later and run ddev avaloi doctor --fix to go back.

7. Make *.ddev.site resolve

NAME.ddev.site is a public name that points to 127.0.0.1. Some routers and DNS filters block names that point at your own computer. If Windows cannot find the site, ddev avaloi doctor shows a dns (Windows) warning. Fix it with a DNS server such as 1.1.1.1 in Windows network settings, or add a line to C:\Windows\System32\drivers\etc\hosts (as administrator): 127.0.0.1 NAME.ddev.site.

Speed

  • Keep the project in ~/projects, not on C:\.
  • Give Docker 4 GB or more.
  • Leave the Windows virus scanner's real-time scan off the \\wsl.localhost path only if your company allows it.
  • Pull only what you need: ddev avaloi pull --db when only data changed.

Not yet

  • Docker Desktop for Windows is not tested with the add-on. Docker Engine inside Ubuntu is.
  • DDEV on plain Windows (PowerShell, Git Bash) is not supported by the add-on.
  • Windows on ARM is not tested.

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.