WESTON(1)

📦
version 16.0.0 · 16 versions
, in ubuntu stonking

🎀 WESTON(1) — General Commands Manual 🎀

okay bestie, welcome to the WESTON(1) page from the General Commands Manual. We're talking about weston, and it's lowkey iconic. This is part 1, so stay with me. 💖

🌸 NAME 🌸

  • weston — a Wayland compositor. periodt 💅

⭐ SYNOPSIS ⭐

The synopsis is literally just this:

weston

💖 DESCRIPTION 💖

weston is a Wayland compositor designed for correctness, reliability, predictability, and performance. A Wayland compositor is a display server, a window manager, and a compositor all in one — it's giving triple threat, no cap. Weston has several backends as loadable modules: it can run on Linux KMS (kernel modesetting via DRM), as an X client, or inside another Wayland compositor instance. 👑

Out of the box, Weston provides a very basic desktop, or a full-featured environment for non-desktop uses such as automotive, embedded, in-flight, industrial, kiosks, set-top boxes and TVs. Like, imagine planes and cars and kiosks and TVs all getting their own Weston moment. Obsessed. ✈️🚗📺

Weston supports fundamentally different graphical user interface paradigms via shell plugins. Multiple plugins are provided: the desktop shell, the kiosk shell, the lua shell, and the ivi shell. Different UI paradigms? The range. The versatility. We love to see it. 🌈

It also provides a library called libweston which allows users to build their own custom full-featured environments on top of Weston's core. Build your own main character environment, fr fr. 🛠️

Weston also supports X clients via Xwayland, see below. We'll get to that, bestie. 👀

🦋 BACKENDS 🦋

These are the loadable modules that let Weston run in different places. Pick your fighter:

  • drm — The DRM backend uses Linux KMS for output and evdev devices for input. It supports multiple monitors in a unified desktop with DPMS. See weston-drm(7), if installed. 💻
  • wayland — The Wayland backend runs on another Wayland server, a different Weston instance, for example. Weston shows up as a single desktop window on the parent server. 🪟
  • x11 — The X11 backend runs on an X server. Each Weston output becomes an X window. This is a cheap way to test multi-monitor support of a Wayland shell, desktop, or applications. 🖥️
  • rdp — The RDP backend runs in memory without the need of graphical hardware. Access to the desktop is done by using the RDP protocol. Each connecting client has its own seat making it a cheap way to test multi-seat support. See weston-rdp(7), if installed. 🔌
  • vnc — The VNC backend runs in memory without the need of graphical hardware. Access to the desktop is done by using the RFB protocol. Currently only one connecting client is supported. See weston-vnc(7), if installed. 🖼️
  • pipewire — The PipeWire backend runs in memory without the need of graphical hardware and creates a PipeWire node for each output. It can be used to capture Weston outputs for processing with another application. 🎛️
  • headless — The headless backend runs in memory. It can be used to capture Weston outputs or to test client applications. 👻

🎀 SHELLS 🎀

Weston's user interface is implemented by individual 'shell' plugins. A number of shells are provided for different usecases. Choose your aesthetic:

  • desktop — The desktop shell is Weston's default mode. It provides an example of a desktop-like environment, featuring a panel with launchers and a clock, a background, and an interactive task switcher. Whilst not intended to be a full-fledged desktop environment in and of itself, it is an example of how such an environment can be built. 🖥️✨
  • kiosk — The kiosk shell is intended for environments which want to run a single application at a time. Applications will be made full screen and activated as they are started. 📺
  • ivi — The IVI shell is a special-purpose shell which exposes an API compatible with the GENIVI Layer Manager to user-provided HMI controller modules. It is intended for use in automotive environments. 🚗
  • lua — The lua shell is a meta-shell that is user-scriptable and configurable. A supplied Lua script will be interpreted and executed by Weston, allowing full control over window management in response to events. 🌙

🔥 XWAYLAND 🔥

Weston can support X11 clients running within a Weston session via an X server called Xwayland. Xwayland is built as a separate executable, provided by X.Org. Once built and installed, it can be activated with the --xwayland option. Weston will listen on a new X11 display socket and export it through the DISPLAY environment variable. X11 clients? In my Weston? It's more likely than you think. 👑

It has also its own X window manager where cursor themes and sizes can be chosen using XCURSOR_PATH and XCURSOR_SIZE environment variables. See ENVIRONMENT. 🎀

💅 OPTIONS 💅

okay bestie, this is the part where weston gets choices. Every single flag, no skips, we're doing the whole menu. 🫶

✨ Weston core options ✨

  • -Bbackend1,backend2, --backend=backend1,backend2 — loads that comma-separated list of backends instead of the default one (peep BACKENDS for the tea). The backend modules get searched for in /usr/lib/x86_64-linux-gnu/weston. Default backend is drm, unless the environment is like "actually no" — see DISPLAY and WAYLAND_DISPLAY. The first backend is the primary backend and it's the one providing the renderer. Heads up: not every backend can be loaded as a secondary backend, because secondary backends reuse the primary backend's renderer. 👑
  • -cconfig.ini, --config=config.ini — load config.ini instead of the usual weston.ini. The argument can also be an absolute path starting with a /. If the path isn't absolute, it gets searched in the normal config paths — see weston.ini(5). This option is ignored if you passed --no-config. 🙈
  • --debug — turns on the debug protocol extension weston_debug_v1, which any client can use to receive debugging messages from the compositor.
⚠️ WARNING, bestie, this is risky for TWO reasons. First: a client may cause a denial-of-service, blocking the compositor entirely, by handing over an unsuitable file descriptor. Second: the debug messages may expose sensitive information. On top of that, this exposes the weston-output-capture interface, letting the user take screenshots of the outputs with the weston-screenshooter application — which can silently leak the contents of your output. Do NOT use this in production. Periodt.
  • -dscope1,scope2, --debug-scopes=scope1,scope2 — says which debug scopes should be advertised over the weston-debug protocol. If you don't specify this, all possible debug scopes get advertised. This option does not secretly turn --debug on for you — you need that set separately for this option to do literally anything. 😌
  • -fscope1,scope2, --flight-rec-scopes=scope1,scope2 — says which scopes to subscribe to. Handy for controlling which streams write data into the flight recorder. The flight recorder has limited space, and once it's full, new data overwrites the old data. With no scopes specified, it subscribes to the log and drm-backend scopes. Passing an empty value disables the flight recorder entirely. 🛬
  • -h, --help — print a summary of the command line options and dip. ✌️
  • -iN, --idle-time=N — sets the idle timeout to N seconds. Default is 300 seconds. When there's been no user input for the idle timeout, Weston enters an inactive mode: the screen fades to black, monitors may switch off, and the shell may lock the session. A value of 0 effectively disables the timeout. 💤
  • --log=file.log — append log messages to the file file.log instead of writing them to stderr.
  • -lscope1,scope2, --logger-scopes=scope1,scope2 — says which log scopes should subscribe. When no scopes are supplied, the log scope gets subscribed by default. Useful for controlling which streams write data into the logger, and it can help when you're diagnosing early start-up code. 🔍
  • --modules=module1.so,module2.so — load that comma-separated list of modules. Only used by the test suite. The file gets searched for in /usr/lib/x86_64-linux-gnu/weston, or you can pass an absolute path.
  • --no-config — don't read weston.ini for the compositor. Avoids stuff like loading compositor modules via the configuration file, which is useful for unit tests. 🧪
  • --renderer=renderer — pick which renderer to use for Weston's internal composition. Defaults to automatic selection.
  • --shell=shell — pick which shell to load to provide Weston's user interface. See ENVIRONMENT.
  • -Sname, --socket=name — Weston will listen on the Wayland socket called name. Weston exports WAYLAND_DISPLAY with this value in the environment for all child processes, so they can find the right server automatically. 💫
  • --version — print the program version. (yep, in the original this little guy is just chilling at the end of the -S entry, we're giving it its own bullet, it's earned it 🎀)
  • --wait-for-debugger — raises SIGSTOP before initializing the compositor. This lets the user attach with a debugger and continue execution by sending SIGCONT. Useful for debugging a crash on start-up when it'd be inconvenient to launch weston directly from a debugger. There's also a weston.ini option that does the same thing. 🐛
  • --xwayland — support X11 clients through the Xwayland server. ✨

🌈 DRM backend options 🌈

See weston-drm(7).

🦋 Wayland backend options 🦋

  • --display=display — name of the Wayland display to connect to, see also WAYLAND_DISPLAY of the environment.
  • --fullscreen — create a single fullscreen output. 🖥️
  • --output-count=N — create N Wayland windows to emulate the same number of outputs.
  • --width=W, --height=H — make all outputs have a size of Wx*H* pixels.
  • --scale=N — give all outputs a scale factor of N.
  • --use-pixman — deprecated in favour of the --renderer option. Use the pixman renderer. By default weston will try to use EGL and GLES2 for rendering, and will fall back to the pixman-based renderer for software compositing if EGL can't be used. Passing this option forces weston to use the pixman renderer.

💜 X11 backend options 💜

  • --fullscreen
  • --no-input — don't provide any input devices. Used for testing input-less Weston.
  • --output-count=N — create N X windows to emulate the same number of outputs.
  • --width=W, --height=H — make the default size of each X window Wx*H* pixels.
  • --scale=N — give all outputs a scale factor of N.
  • --use-pixman — deprecated in favour of the --renderer option. Use the pixman renderer. By default weston will try to use EGL and GLES2 for rendering. Passing this option makes weston use the pixman library for software compsiting. 💀

🔥 RDP backend options 🔥

See weston-rdp(7).

🌸 VNC backend options 🌸

See weston-vnc(7).

⭐ headless backend options ⭐

  • --width=W, --height=H — make the default size of each output Wx*H* pixels.
  • --scale=N — give all outputs a scale factor of N.
  • --transform=transform — transform for the output, which can be rotated in 90-degree steps and possibly flipped. Possible values are normal, rotate-90, rotate-180, rotate-270, flipped, flipped-rotate-90, flipped-rotate-180, and flipped-rotate-270. 🌀
  • --no-outputs — don't create any virtual outputs.
  • --refresh-rate=N — give all outputs a refresh rate of N mHz (60,000 mHz by default). Supported values range from 0 mHz to 1,000,000 mHz. 0 is a special value that repaints as soon as possible on capture requests only — not on damages. 👀

🎀 lua shell options 🎀

  • --lua-script=script — override weston.ini lua-script= with script. The path can be either absolute or relative using the current working directory.

📁 FILES 📁

If the environment variable is set, the configuration file is read from the respective path.

  • $XDG_CONFIG_HOME/weston.ini
  • $HOME/.config/weston.ini

🌍 ENVIRONMENT 🌍

  • DISPLAY — the X display. If DISPLAY is set, and WAYLAND_DISPLAY is not set, the default backend becomes x11.
  • WAYLAND_DEBUG — if set to any value, causes libwayland to print the live protocol to stderr. 🐞
  • WAYLAND_DISPLAY — the name of the display (socket) of an already running Wayland server, without the path. The directory path is always taken from XDG_RUNTIME_DIR. If WAYLAND_DISPLAY is not set, the socket name is "wayland-0".

If WAYLAND_DISPLAY is already set, the default backend becomes wayland. This is what lets you launch Weston as a nested server. 🪆

  • WAYLAND_SOCKET — for Wayland clients, holds the file descriptor of an open local socket to a Wayland server.
  • WESTON_CONFIG_FILE — Weston sets this variable to the absolute path of the configuration file it loads, or to the empty string if no file is used. Programs that use weston.ini will read the file specified by this variable instead, or won't read any file if it's empty. An unset variable causes falling back to the default name weston.ini.
  • XCURSOR_PATH — set the list of paths to look for cursors in. It changes both libwayland-cursor and libXcursor, so it affects both Wayland and X11 based clients. See xcursor (3). 🖱️
  • XCURSOR_SIZE — this variable can be set for choosing an specific size of cursor. Affects Wayland and X11 clients. See xcursor (3).
  • XDG_CONFIG_HOME — if set, specifies the directory where to look for weston.ini.
  • XDG_RUNTIME_DIR — the directory for Weston's socket and lock files. Wayland clients will automatically use this.

🚀 PROGRAM EXECUTION 🚀

okay so YES, you can make Weston run a program for you. it's giving "personal assistant". 💁‍♀️

Here's the syntax:

weston [options] -- [program [arguments]]

That -- right there is mandatory to execute a program. Examples are down in the EXAMPLES section, go look. ✨

🐛 BUGS 🐛

Bugs should be reported to

https://gitlab.freedesktop.org/wayland/weston/

(we don't shoot the messenger, we file the issue, bestie 🫶)

🌐 WWW 🌐

https://wayland.freedesktop.org/

🌟 EXAMPLES 🌟

Launch Weston with the DRM backend on a VT

weston

Launch Weston with the DRM backend and XWayland support

weston --xwayland

Launch Weston (wayland-1) nested in another Weston instance (wayland-0)

WAYLAND_DISPLAY=wayland-0 weston -Swayland-1

From an X terminal, launch Weston with the x11 backend

weston

Launch Weston and make it start weston-terminal

weston -- /usr/local/bin/weston-terminal

Launch Weston with the kiosk shell and make it start weston-simple-egl

weston --shell=kiosk-shell.so -- /usr/local/bin/weston-simple-egl

Launch Weston with the kiosk shell and open a pdf document with mupdf

weston --shell=kiosk-shell.so -- mupdf
/home/user/Documents/krh/wayland.pdf

👀 SEE ALSO 👀

weston-bindings(7), weston-debug(1), weston-drm(7), weston-rdp(7), weston-vnc(7), weston.ini(5)

and that's the whole page, bestie!! 🎀✨ this is Weston 16.0.0, dated 2026-01-30 — go forth and compose some wayland, you absolute icon. no cap, you ate that. 💅💖🦋

📦 where this page comes from