Building and Running on WSL

To run non-headless servo shell on WSL, you will most likely need to be on Windows 10 Build 19044+ or Windows 11 as access to WSL v2 is needed for GUI.

Building

Servo can be built on WSL as if you are building on any other Linux distribution.

1. Setup WSL v2. See Microsoft's guidelines for setting up GUI apps in WSL.
2. Set up the environment depending on the WSL distribution that you are using (e.g. Ubuntu, OpenSuse, etc.)
3. Build ./mach build

Running

WSL v2 has the corresponding adaptors to display Wayland and X11 applications, though it may not always work out of the box with Servo.

./mach run

Troubleshooting

Failed to create event loop:

If you encounter an immediate crash after running that points to winit and its platform implementation, setting WAYLAND_DISPLAY='' stops the crash.

Failed to create events loop: Os(OsError { line: 81, file: "/home/astra/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/winit-0.30.9/src/platform_impl/linux/wayland/event_loop/mod.rs", error: WaylandError(Connection(NoCompositor)) }) (thread main, at ports/servoshell/desktop/cli.rs:34)
   0: servoshell::backtrace::print
             at /home/astra/workspace/servo/ports/servoshell/backtrace.rs:18:5
  ...
  18: main
  19: <unknown>
  20: __libc_start_main
  21: _start
Servo was terminated by signal 11

Either export the variable, or set it before running:

export WAYLAND_DISPLAY=''
./mach run

# or

WAYLAND_DISPLAY='' ./mach run

# optionally save the variable long term to your .bashrc profile

echo 'export WAYLAND_DISPLAY=""' >> ~/.bashrc

Library libxkbcommon-x11.so could not be loaded:

This may happen because your distro have not installed the required library. Run the following command (assuming you are using WSL Debian/Ubuntu, adjust accordingly if you use other distro):

sudo apt install libxkbcommon-x11-0

Error while running ./mach build:

if you encounter an error like below while running ./mach build on WSL, it is possibly caused by out of memory (OOM) error because your WSL does not have enough RAM to build servo. You will need to increase memory usage limit and swapfile on WSL, or upgrade your RAM to fix it.

yourusername@PC:~/servo$ ./mach build
No build type specified so assuming `--dev`.
Building `debug` build with crown disabled (no JS garbage collection linting).
   ...
   Compiling script v0.0.1 (/home/yourusername/servo/components/script)

error: failed to run build command...

Caused by:
  process didn't exit successfully: `/home/yourusername/.rustup/toolchains/1.91.0-x86_64-unknown-linux-gnu/bin/rustc --crate-name script --edition=2024 components/script/lib.rs...
  ...
warning: build failed, waiting for other jobs to finish...

Create C:/user/yourusername/.wslconfig then insert the following:

[wsl2]
memory=6GB
swap=16GB
swapfile=C:\\Users\\yourusername\\swapfile.vhdx

Save the file and restart WSL on powershell:

wsl --shutdown