Windows Setup

Overview

Running graphical Docker containers on Windows requires Docker Desktop with WSL2 backend and an X server for display forwarding. This guide covers the complete setup process for Windows users.

Prerequisites

Before you begin, ensure you have:

Windows 10 version 2004 or higher, or Windows 11
WSL2 installed and configured
Docker Desktop for Windows installed

Setup Steps

Install WSL2

WSL2 (Windows Subsystem for Linux 2) is required for Docker Desktop on Windows.Open PowerShell as Administrator and run:

wsl --install

This command will:

Enable the WSL feature
Install the Ubuntu distribution (default)
Set WSL2 as the default version

After installation, you must reboot your computer for the changes to take effect.

Verify WSL2 is installed:

wsl --list --verbose

You should see your Linux distribution listed with version 2.

Install Docker Desktop

Download and install Docker Desktop for Windows:

Download from https://www.docker.com/products/docker-desktop/
Run the installer
Ensure “Use WSL 2 instead of Hyper-V” is selected during installation
Restart your computer when prompted

After installation, open Docker Desktop and ensure it’s running. You should see the Docker icon in your system tray.Configure Docker Desktop:

Open Docker Desktop
Go to Settings → General
Ensure “Use the WSL 2 based engine” is checked
Go to Settings → Resources → WSL Integration
Enable integration with your WSL2 distributions

Install an X Server

Windows doesn’t have a native X server, so you need to install one. We recommend VcXsrv.

VcXsrv (Recommended)

Download and Install:

Download VcXsrv from SourceForge
Run the installer with default settings

Configure VcXsrv:

Launch XLaunch (VcXsrv)
Select “Multiple windows” → Next
Select “Start no client” → Next
Important: Check these boxes:
- “Clipboard” (optional, for clipboard sharing)
- “Primary Selection” (optional)
- “Disable access control” (required for Docker containers)
Click “Finish”

Save the configuration for future use by clicking “Save configuration” before finishing.

Xming (Alternative)

Download and Install:

Download Xming from SourceForge
Run the installer

Launch Xming:

Run Xming from the Start menu
You should see the Xming icon in your system tray
Configure it to disable access control for Docker

Configure Display Environment

You need to set the DISPLAY environment variable to point to your Windows X server.Open your WSL2 terminal and add this to your ~/.bashrc or ~/.profile:

# Get Windows host IP address
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

Alternatively, if you’re using WSL2 with localhost access (newer versions):

export DISPLAY=:0

Apply the changes:

source ~/.bashrc

The DISPLAY variable tells Docker containers where to send graphical output. It points to your Windows X server.

Test the Connection

In your WSL2 terminal, verify the DISPLAY variable:

echo $DISPLAY

You should see an IP address followed by :0, or just :0 depending on your configuration.

Running the Container

From your WSL2 terminal, run the container with the following command:

docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    raylib_container

Parameter Explanation:

-it: Starts the container in interactive mode with a terminal attached
--rm: Automatically removes the container when it exits
-e DISPLAY=$DISPLAY: Passes the DISPLAY variable to the container
-v /tmp/.X11-unix:/tmp/.X11-unix: Mounts the X11 socket directory
-v ./user_code:/app/user_code: Mounts your code directory into the container
raylib_container: The name of the Docker image

Verifying Graphics Connection

Once inside the container, test the graphics connection:

xeyes

A window with eyes that follow the mouse should appear on your Windows desktop. If it does, your setup is working correctly!

If xeyes works, you’re ready to run Raylib applications in the container!

Hardware Acceleration

Hardware acceleration (GPU passthrough) is limited on Windows with Docker Desktop and WSL2. Most setups will use software rendering.

Current Limitations

Direct GPU passthrough to containers is not fully supported on Windows
The --device /dev/dri:/dev/dri flag used on Linux won’t work
Graphics rendering will primarily use CPU (software rendering)

Improving Performance

While hardware acceleration isn’t fully available, you can improve performance:

Allocate more resources to Docker:
- Open Docker Desktop → Settings → Resources
- Increase CPU count and Memory allocation
Allocate more resources to WSL2: Create/edit %USERPROFILE%\.wslconfig:
```
[wsl2]
memory=4GB
processors=4
```
Restart WSL2:
```
wsl --shutdown
```
Use lower resolutions during development:
- Test with smaller window sizes
- Reduce asset complexity

Common Workflows

Starting a Development Session

Start VcXsrv

Launch XLaunch and configure it (or use your saved configuration).

Open WSL2 Terminal

Open your WSL2 distribution (e.g., Ubuntu) from the Start menu or Windows Terminal.

Navigate to Your Project

cd /mnt/c/Users/YourName/your-project

Your Windows drives are mounted under /mnt/ in WSL2. For example, C:\ is /mnt/c/.

Run the Container

docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    raylib_container

Creating a Launch Script

Create a script to simplify launching:

#!/bin/bash
# save as start-raylib.sh in WSL2

# Ensure DISPLAY is set
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

echo "DISPLAY is set to: $DISPLAY"
echo "Make sure VcXsrv is running on Windows!"
echo ""

# Run the container
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    raylib_container

Make it executable:

chmod +x start-raylib.sh
./start-raylib.sh

Troubleshooting

Error: Cannot connect to Docker daemon

Full error: Cannot connect to the Docker daemon at unix:///var/run/docker.sockSolutions:

Ensure Docker Desktop is running (check system tray)
Verify WSL integration is enabled in Docker Desktop settings
Restart Docker Desktop
In WSL2, run: docker ps to verify connection

Graphics window doesn't appear

Symptoms: Container runs but no graphics window appearsSolutions:

Verify VcXsrv is running (check system tray for X icon)
Check DISPLAY variable:
```
echo $DISPLAY
```
Should show an IP address or :0
Ensure VcXsrv has “Disable access control” checked
Check Windows Firewall:
- Allow VcXsrv through the firewall
- Settings → Update & Security → Windows Security → Firewall & network protection
Try using localhost:
```
export DISPLAY=:0
```

Error: Can't open display

Full error: Error: Can't open display: <IP>:0Solutions:

Restart VcXsrv with access control disabled
Verify the DISPLAY IP matches your Windows host:
```
cat /etc/resolv.conf | grep nameserver
```

Try alternative DISPLAY configurations:

export DISPLAY=:0
# or
export DISPLAY=localhost:0

Check that VcXsrv is listening on the correct port (6000)

Slow graphics performance

Cause: Software rendering without GPU accelerationSolutions:

This is expected on Windows with Docker
Increase Docker Desktop resources (Settings → Resources)
Edit .wslconfig to allocate more memory/CPU to WSL2
Reduce window size and graphics complexity
For production testing, use a Linux machine

WSL2 not found / not installed

Solutions:

Ensure Windows version is 2004 or higher:
- Press Win+R, type winver, check version

Run in PowerShell (Admin):

wsl --install
wsl --set-default-version 2

Verify installation:
```
wsl --list --verbose
```
Reboot after installation

File Paths and Volume Mounting

Accessing Windows Files from WSL2

Your Windows drives are mounted under /mnt/:

# Windows C:\Users\YourName\Documents
# In WSL2: /mnt/c/Users/YourName/Documents

cd /mnt/c/Users/YourName/Documents/raylib-project

Recommended Project Structure

Store your projects in the WSL2 filesystem for better performance:

# In WSL2 home directory
mkdir -p ~/raylib-projects/my-game
cd ~/raylib-projects/my-game
mkdir user_code

Files in the WSL2 filesystem (~/...) have better performance than files on Windows drives (/mnt/c/...) when used with Docker.

Known Limitations

Important limitations when using Docker on Windows:

No GPU acceleration - Graphics rendering uses CPU only
Performance overhead - WSL2 translation layer adds some overhead
File I/O - File operations can be slower, especially on /mnt/ drives
Network complexity - DISPLAY forwarding requires X server configuration

Workarounds

For performance-critical development, consider dual-booting Linux or using a Linux VM
Use Windows-native tools for final builds and testing
Keep development assets minimal to reduce rendering load
Consider developing natively on Windows and using the container for CI/CD

Getting Started

Setup & Deployment

Development

Platform Guides

Troubleshooting

Overview

Prerequisites

Setup Steps

Running the Container

Verifying Graphics Connection

Hardware Acceleration

Current Limitations

Improving Performance

Common Workflows

Starting a Development Session

Creating a Launch Script

Troubleshooting

File Paths and Volume Mounting

Accessing Windows Files from WSL2

Recommended Project Structure

Known Limitations

Workarounds

Next Steps

Build the Image

Quick Start

Build docs developers (and LLMs) love

Getting Started

Setup & Deployment

Development

Platform Guides

Troubleshooting

​Overview

​Prerequisites

​Setup Steps

​Running the Container

​Verifying Graphics Connection

​Hardware Acceleration

​Current Limitations

​Improving Performance

​Common Workflows

​Starting a Development Session

​Creating a Launch Script

​Troubleshooting

​File Paths and Volume Mounting

​Accessing Windows Files from WSL2

​Recommended Project Structure

​Known Limitations

​Workarounds

​Next Steps

Build the Image

Quick Start

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup Steps

Running the Container

Verifying Graphics Connection

Hardware Acceleration

Current Limitations

Improving Performance

Common Workflows

Starting a Development Session

Creating a Launch Script

Troubleshooting

File Paths and Volume Mounting

Accessing Windows Files from WSL2

Recommended Project Structure

Known Limitations

Workarounds

Next Steps