Windows (WSL2)

boks runs on Windows through WSL2 (Windows Subsystem for Linux 2). Once WSL2 is set up, the installation and usage are identical to Linux.

Requirements

• Windows 10 version 2004 or later, or Windows 11
• WSL2 enabled

Step 1: Install WSL2

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 with Ubuntu. Restart when prompted.

To use a different distribution:

wsl --install -d Ubuntu-22.04

Step 2: Install Podman in WSL2

Open your WSL2 terminal:

sudo apt update
sudo apt install podman
podman --version

Step 3: Install boks

curl -fsSL https://boks.sh/install | sh
export PATH="$HOME/.local/bin:$PATH"
boks --help

Add the PATH line to ~/.bashrc to make it permanent.

Step 4: Run a tool

echo '{"ok":true}' | boks jq '.ok'

Common issues

"slirp4netns not found"

Install the required network dependencies:

sudo apt install slirp4netns fuse-overlayfs

Slow performance

Store projects in the WSL2 filesystem (~/projects/) rather than the Windows filesystem (/mnt/c/). Cross-filesystem I/O is significantly slower.

DNS not resolving inside containers

# Edit /etc/wsl.conf
[network]
generateResolvConf = false

Then create /etc/resolv.conf:

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Restart WSL: wsl --shutdown in PowerShell.

WSL memory

If containers are slow or crash, increase WSL2 memory. Create %USERPROFILE%\.wslconfig on Windows:

[wsl2]
memory=8GB
processors=4

Restart WSL: wsl --shutdown.