Skip to main content
SerenityOS can be built and run under WSL Version 2. WSL Version 1 is not supported since it lacks ext2 filesystem support.

​
Prerequisites

WSL Version 2 requires:
  • Windows 10 version 2004 or higher
  • OS Build 19041 or greater

​
Installing WSL2

1

Install WSL2

Follow the official Microsoft guide: Get WSL2
2

Verify WSL version

Check your installed distributions and versions:
wsl -l -v
3

Convert to WSL2 (if needed)

If your distribution is using Version 1, convert it:
wsl --set-version <distro> 2
4

Set default version (optional)

To make WSL2 the default for all new distributions:
wsl --set-default-version 2

​
Install Build Dependencies

Once WSL2 is set up, follow the Linux build instructions for your chosen distribution:

Ubuntu/Debian

Most common choice for WSL2

Other Distributions

Arch, Fedora, and more

​
Filesystem Performance

Critical Performance Note:WSL2 filesystem performance for IO-heavy tasks (like compiling C++ projects) is significantly slower on the Windows filesystem compared to the Linux filesystem.
Store your project in the Linux filesystem: 
# Clone to Linux filesystem
cd ~
git clone https://github.com/SerenityOS/serenity.git
cd serenity

​
Accessing Linux Files from Windows

You can access your Linux filesystem from Windows Explorer at: 
\\wsl$\<distro-name>\home\<username>\serenity
For example: 
\\wsl$\Ubuntu\home\john\serenity
This allows you to use Windows editors and tools while keeping the build fast.

​
Setting up QEMU

1

Download QEMU for Windows

Download the latest QEMU binaries from qemu.org
2

Install required components

During installation, select at minimum:
  • Tools
  • System emulators (i386 and x86_64)
  • DLL libraries QEMU Components
3

Build and run SerenityOS

Meta/serenity.sh run

​
Hardware Acceleration

By default, QEMU runs in software virtualization mode, which is very slow. Enable hardware acceleration for better performance:
1

Enable Windows Hypervisor Platform

  1. Open “Turn Windows features on or off”
  2. Check Windows Hypervisor Platform
  3. Click OK WHPX Feature
2

Reboot

You may need to reboot after enabling WHPX.
3

Run SerenityOS

QEMU will automatically use WHPX when available:
Meta/serenity.sh run

​
Advanced Filesystem Configuration

​
Using Native Windows Partitions

For better QEMU performance, you can copy the disk image to a native Windows partition: 
# Copy disk image to Windows C: drive
cp Build/_disk_image /mnt/c/serenity/_disk_image
cp Build/Kernel/Kernel /mnt/c/serenity/Kernel
Then configure SERENITY_DISK_IMAGE to point to the Windows path (e.g., D:\serenity\_disk_image).
This avoids the 9P network filesystem overhead when accessing WSL2 files from Windows QEMU.

​
WSL Network Path

The root of your WSL2 distribution is accessible from Windows at: 
\\wsl$\{distro-name}

​
Troubleshooting

​
WSL Version Issues

If you’re unsure about your WSL version: 
# List distributions and versions
wsl -l -v

# Should show VERSION 2

​
Performance Problems

If builds are very slow:
  1. Verify you’re using Linux filesystem (not /mnt/c/)
  2. Check current directory: 
    pwd
# Should be /home/<user>/... NOT /mnt/c/...

​
QEMU Launch Failures

If QEMU doesn’t start:
  1. Verify QEMU is in Windows PATH
  2. Check QEMU installation: 
    qemu-system-x86_64 --version
  3. Ensure hardware acceleration is enabled

​
File Permission Errors

If you encounter permission issues: 
# Fix executable permissions
chmod +x Meta/serenity.sh
chmod +x Toolchain/*.sh

​
Best Practices

Always clone and build in /home/ or /root/, never in /mnt/c/ or other Windows mounts.
WHPX provides massive performance improvements. Always enable it.
Access your Linux files via \\wsl$\ to use VS Code, Sublime, or other Windows editors.
Configure WSL2 memory and CPU limits in .wslconfig:
[wsl2]
memory=8GB
processors=4

​
Next Steps

Build System Overview

Learn about the SuperBuild system

Advanced Options

Explore CMake options and customization

Build docs developers (and LLMs) love

Get started for freeTalk to us