Install NOMAD on Windows via WSL2

Who this is for

You have a Windows 10 (build 19041 or later) or Windows 11 PC and want to run NOMAD without buying a separate Linux machine or wiping Windows. WSL2 makes that possible — with caveats.

You should have at least 16 GB of RAM (32 GB+ recommended if you want the AI Assistant), and roughly 100 GB of free disk for the OS, NOMAD images, and content libraries.

Will my GPU work?

GPU acceleration for the AI Assistant depends entirely on your GPU vendor.

The AMD/Intel limits are upstream — ROCm-on-WSL has a narrow allowlist that excludes most consumer cards, and there's no Vulkan-based Ollama path in NOMAD today. Bare-metal Ubuntu is the answer for AMD GPU users.

How does it actually perform?

We ran the NOMAD benchmark on the same Threadripper 3960X chassis in three configurations to give you real numbers, not guesswork.

The headline: AI inference runs about 18% faster on bare-metal Ubuntu than under WSL2 with the same NVIDIA card. Time-to-first-token drops from 7 ms to 5 ms. Disk writes also speed up because there's no NTFS overlay between the container and your storage.

Composite NOMAD scores all sit within ~2 points of each other, so for general use (Wikipedia, Kolibri, knowledge content), WSL2 is fine. If you're going to be running the AI Assistant heavily, or doing AMD GPU acceleration, bare-metal Ubuntu wins clearly.

Pick your install path

Two install paths work. They differ in whether Docker runs natively in WSL or via Docker Desktop on Windows.

Whichever path you pick, the five WSL2 gotchas at the bottom of this page apply equally to both. Read those before you start.

1. Install WSL2 with Ubuntu 24.04

From PowerShell as Administrator on Windows:

$ wsl --install -d Ubuntu-24.04

Reboot when prompted, then open Ubuntu from the Start menu and create a Linux username and password.

2. Enable systemd in WSL

Inside Ubuntu, set up /etc/wsl.conf with systemd enabled and the rshared mount fix that WSL2 needs for the disk-collector container:

sudo tee /etc/wsl.conf > /dev/null <<'EOF'
[boot]
systemd=true
command="mount --make-rshared /"
EOF

Then from PowerShell:

$ wsl --shutdown

Reopen Ubuntu. The shutdown is required — closing the terminal isn't enough. WSL only re-reads wsl.conf on a fresh boot.

3. Disable Docker Desktop's WSL integration (if installed)

If Docker Desktop is installed on Windows, its WSL integration will conflict with the apt Docker install you're about to do. Open Docker Desktop, go to Settings → Resources → WSL integration, and uncheck your Ubuntu distro. Click Apply & Restart. If Apply fails, just quit Docker Desktop entirely.

Then run wsl --shutdown from PowerShell again and reopen Ubuntu.

If you don't have Docker Desktop, skip this step.

4. Remove snap-installed Docker (if present)

Snap Docker is sandboxed and can't access /opt, where NOMAD installs. If you have it:

$ sudo snap remove --purge docker

If snap list | grep docker returns nothing, you're fine.

5. Install Docker

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Close and reopen the Ubuntu shell so the docker group membership takes effect.

6. Run the NOMAD install script

sudo apt-get update && \
sudo apt-get install -y curl && \
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh -o install_nomad.sh && \
sudo bash install_nomad.sh

Accept the license prompt and let it run. About five minutes for image pulls.

7. Open NOMAD

On the Windows host, open a browser and go to http://localhost:8080.

WSL2 forwards localhost to the WSL distro automatically, so no extra setup is needed for browser access from Windows. To reach NOMAD from another LAN machine, you'll need a netsh portproxy rule on the Windows host (covered later in the gotchas section).

This path is based on @nielseni6's walkthrough in #260 with minor updates for current install script behavior.

1. Install WSL2 with Ubuntu and enable systemd

Same as Path A steps 1 and 2 — install Ubuntu, set up /etc/wsl.conf with systemd and rshared mount, then wsl --shutdown and reopen.

2. Install Docker Desktop and enable WSL integration

Download Docker Desktop and install with the default options (the WSL2 backend is the default on Windows 11 and recommended on Windows 10).

After install, open Docker Desktop, go to Settings → Resources → WSL integration, and toggle on your Ubuntu distro. This makes docker and docker compose available inside WSL.

3. Download the NOMAD install script

sudo apt-get update && sudo apt-get install -y curl
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh -o install_nomad.sh

4. Patch the script for Docker Desktop

The install script checks systemctl is-active docker to verify Docker is running. With Docker Desktop, the daemon lives on the Windows side — there's no docker.service systemd unit, so the check fails. Replace it with docker info:

sed -i 's|systemctl is-active --quiet docker|docker info \&> /dev/null|g' install_nomad.sh

That's the only change needed.

5. Run the install

$ sudo bash install_nomad.sh

6. Open NOMAD

Open http://localhost:8080 in your Windows browser. Done.

Reboot workflow for Path B

After a Windows reboot, Docker Desktop must be running before NOMAD's containers can start. Either enable Docker Desktop to launch at sign-in (Settings → General → Start Docker Desktop when you sign in), or start it manually and then run:

$ sudo bash /opt/project-nomad/start_nomad.sh

Five WSL2 gotchas that bite both paths

Whichever install path you pick, you'll run into some subset of these. Documented here as a single reference rather than scattered through both walkthroughs.

$ sudo mount --make-rshared /

$ netstat -ano | findstr :11434

$ sudo systemctl disable --now ollama

docker exec nomad_ollama nvidia-smi
docker logs nomad_ollama 2>&1 | grep -i "library="

Access NOMAD from other LAN machines

http://localhost:8080 works from your Windows browser automatically. To reach NOMAD from another machine on the LAN, set up a port proxy on the Windows host. From PowerShell as Administrator:

netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=127.0.0.1
New-NetFirewallRule -DisplayName "NOMAD 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

Repeat for each port you want exposed (8090 Kiwix, 8300 Kolibri, etc.). Using 127.0.0.1 as connectaddress works because of WSL2's localhost forwarding — you don't need to chase the WSL distro's internal IP, which can drift across boots.

Community credit

This guide builds on substantial prior work from the NOMAD community.

• @nielseni6 wrote the original step-by-step Docker Desktop + WSL Integration walkthrough in issue #260. Path B above is a direct descendant of their work.
• @charlesmerritt investigated the install_nomad.sh-side WSL2 patches in issue #572. The script-level diagnosis there informed several of the gotchas above.

Get help

Hit a problem this guide doesn't cover? Post in GitHub Discussions with your Windows version, WSL distro version, and the full error you're seeing. Other Windows users are likely watching the discussion forum and may have hit the same thing.

Please don't open bug reports against the install script for WSL2-specific issues — WSL2 isn't officially supported, and we can't triage every Windows configuration. The discussions forum is the right place.