weston - the reference Wayland server
is the reference implementation of a Wayland server. A Wayland
server is a display server, a window manager, and a compositor all in one.
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 server
Weston supports fundamentally different graphical user interface paradigms via
shell plugins. Two plugins are provided: the desktop shell, and the tablet
When weston is started as the first windowing system (i.e. not under X nor under
another Wayland server), it should be done with the command
to set up proper privileged access to devices.
Weston also supports X clients via XWayland
, see below.
- 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.
- 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.
- 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.
Each of these shells have its own public protocol interface for clients. This
means that a client must be specifically written for a shell protocol,
otherwise it will not work.
- Desktop shell
- Desktop shell is like a modern X desktop environment,
concentrating on traditional keyboard and mouse user interfaces and the
familiar desktop-like window management. Desktop shell consists of the
shell plugin desktop-shell.so and the special client
weston-desktop-shell which provides the wallpaper, panel, and
screen locking dialog.
- Fullscreen shell
- Fullscreen shell is intended for a client that needs to
take over whole outputs, often all outputs. This is primarily intended for
running another compositor on Weston. The other compositor does not need
to handle any platform-specifics like DRM/KMS or evdev/libinput. The shell
consists only of the shell plugin fullscreen-shell.so.
- In-vehicle infotainment shell is a special purpose shell
that exposes a GENIVI Layer Manager compatible API to controller modules,
and a very simple shell protocol towards clients. IVI-shell starts with
loading ivi-shell.so, and then a controller module which may launch
XWayland requires a special X.org server to be installed. This X server will
connect to a Wayland server as a Wayland client, and X clients will connect to
the X server. XWayland provides backwards compatibility to X applications in a
XWayland is activated by instructing weston
to load the XWayland module,
. Weston starts listening on a new X display socket, and
exports it in the environment variable DISPLAY
. When the first X client
connects, Weston launches a special X server as a Wayland client to handle the
X client and all future X clients.
It has also its own X window manager where cursor themes and sizes can be chosen
environment variables. See
- Load backend.so instead of the default backend. The
file is searched for in /usr/lib/weston, or you can pass an
absolute path. The default backend is drm-backend.so unless the
environment suggests otherwise, see DISPLAY and
- Load config.ini instead of weston.ini. The
argument can also be an absolute path starting with a /. If the
path is not absolute, it will be searched in the normal config paths, see
weston.ini(5). If also --no-config is given, no
configuration file will be read.
- Print the program version.
- -h, --help
- Print a summary of command line options, and quit.
- -iN, --idle-time=N
- Set the idle timeout to N seconds. The default
timeout is 300 seconds. When there has not been any 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.
- Append log messages to the file file.log instead of
writing them to stderr.
- Ask Weston to load the XWayland module.
- Load the comma-separated list of modules. Only used by the
test suite. The file is searched for in /usr/lib/weston, or you can
pass an absolute path.
- Do not read weston.ini for the compositor. Avoids
e.g. loading compositor modules via the configuration file, which is
useful for unit tests.
- -Sname, --socket=name
- Weston will listen in the Wayland socket called
name. Weston will export WAYLAND_DISPLAY with this value in
the environment for all child processes to allow them to connect to the
right server automatically.
- Name of the Wayland display to connect to, see also
WAYLAND_DISPLAY of the environment.
- Create a single fullscreen output
- Create N Wayland windows to emulate the same number
- --width=W, --height=H
- Make all outputs have a size of WxH
- Give all outputs a scale factor of N.
- 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 cannot be used. Passing this
option will force weston to use the pixman renderer.
- Do not provide any input devices. Used for testing
- Create N X windows to emulate the same number of
- --width=W, --height=H
- Make the default size of each X window WxH
- Give all outputs a scale factor of N.
- Use the pixman renderer. By default weston will try to use
EGL and GLES2 for rendering. Passing this option will make weston use the
pixman library for software compsiting.
If the environment variable is set, the configuration file is read from the
respective path, or the current directory if neither is set.
- The X display. If DISPLAY is set, and
WAYLAND_DISPLAY is not set, the default backend becomes
- If set to any value, causes libwayland to print the live
protocol to stderr.
- 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-backend.so. This allows launching Weston as a nested
- For Wayland clients, holds the file descriptor of an open
local socket to a Wayland server.
- 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 do not read any file if it is empty. Unset variable
causes falling back to the default name weston.ini.
- 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).
- This variable can be set for choosing an specific size of
cursor. Affect Wayland and X11 clients. See xcursor (3).
- If set, specifies the directory where to look for
- The directory for Weston's socket and lock files. Wayland
clients will automatically use this.
Weston has a segmentation fault handler, that attempts to restore the virtual
console or ungrab X before raising SIGTRAP
. If you run weston
from an X11 terminal or a different virtual terminal, and
- handle SIGSEGV nostop
This will allow weston to switch back to gdb on crash and then gdb will catch
the crash with SIGTRAP.
Bugs should be reported to the freedesktop.org bugzilla at
https://bugs.freedesktop.org with product "Wayland" and component
- Launch Weston with the DRM backend on a VT
- Launch Weston with the DRM backend and XWayland
- weston-launch -- --xwayland
- Launch Weston (wayland-1) nested in another Weston instance
- WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
- From an X terminal, launch Weston with the x11 backend