XWFB-RUN(1)

✨ xwfb-run(1) — the manual, but make it make sense ✨

okay so real talk, bestie: xwfb-run lives in the General Commands Manual and it's giving "replacement utility" main character energy. Let's get into it 💅

---

🦋 NAME 🦋

xwfb-run — run X11 clients on a dedicated Xwayland server, headless. periodt.

---

🎀 SYNOPSIS 🎀

xwfb-run [option ...] -- COMMAND

like, options first, then --, then the actual command you wanna run. no cap.

---

🌸 DESCRIPTION 🌸

so xwfb-run is intended as a replacement utility for xvfb-run, okay? but instead of using Xvfb, it uses rootful Xwayland running fullscreen on top of a headless compositor. that's the whole vibe. it's the glow-up version 🫶

---

💖 OPTIONS 💖

• -a AUTO_SERVERNUM, --auto-servernum AUTO_SERVERNUM — unused, bestie. it's literally just kept for backward compatibility only. don't come for it 🙈
• -c COMPOSITOR, --compositor COMPOSITOR — use the compositor class implementation.
• -d AUTO_DISPLAY, --auto-display AUTO_DISPLAY — also unused, also just hanging around for backward compatibility only. iconic of it tbh.
• -e ERROR_FILE, --error-file ERROR_FILE — the file used to store xauth and X server errors.
• -f AUTH_FILE, --auth-file AUTH_FILE — the file used to store the auth cookie 🍪
• -n SERVER_NUM, --server-num SERVER_NUM — the X server number to use.
• -l, --listen-tcp — enable TCP port listening in the X server.
• -p XAUTH_PROTO, --xauth-proto XAUTH_PROTO — the Xauthority protocol name to use.
• -s SERVER_ARGS, --server-args SERVER_ARGS — arguments to pass to the X server. heads up though: X server arguments must be escaped with two backslash characters, like this — -s \\-ac.
• -w WAIT, --wait WAIT — delay in seconds to wait for the X server to start before running COMMAND.
• -z COMPOSITOR_ARGS, --compositor-args COMPOSITOR_ARGS — arguments to pass to the Wayland compositor. and same deal, arguments intended for the Wayland compositor must be escaped with two backslash characters, e.g. -z \\--renderer -z gl.

ngl, the double-backslash thing is the #1 place people trip up, so like… don't forget it? please? for me? 😭

---

🧚 FILES 🧚

wlheadless.conf

sets the default compositor to use. lowkey important.

the file is searched in the wlheadless directory relative to the paths specified in the standard environment variables XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_DATA_DIRS.

and inside it, the config is giving:

[DEFAULT]
Compositor = weston

---

👑 SEE ALSO 👑

wlheadless-run(1), xwayland-run(1), Xwayland(1), Xvfb(1)

like, go read those too, iykyk 📚

---

⭐ fun facts before you go: this page is from the General Commands Manual, source/version is XWFB-RUN(1), and it was dated the same day it got filed as XWFB-RUN(1). anyway bestie that's the whole page — go run some headless X clients, slay, and hydrate 💜🦋