Synopsis #
Xorg is an X11 display server. Wayland is a protocol implemented by a compositor, and older X11 applications normally run through Xwayland. The practical choice is therefore not between two interchangeable packages. It is between a tested Xorg session and a particular Wayland compositor or desktop session on the installed graphics driver.
Configure and verify the graphics driver before choosing either stack. A display protocol cannot compensate for a kernel driver that did not attach.
Choose from requirements #
| Requirement | Prefer Xorg when | Prefer Wayland when |
|---|---|---|
| Existing desktop or window manager | Its maintained FreeBSD path is X11 | It provides and documents a supported Wayland session |
| Older X11 applications | Native X11 behavior is important | The applications work correctly through Xwayland |
| Remote graphical use | X11 forwarding or an established Xorg remote workflow is required | The compositor’s VNC or RDP method has been tested |
| NVIDIA graphics | The applicable driver has a stable Xorg path but compositor support is uncertain | The current DRM driver and selected compositor are documented to work together |
| Minimal configuration | A known Xorg desktop session already works | A compositor package provides a complete maintained session |
| Input and screen-sharing tools | They depend on X11 facilities | Their portal and compositor integration is available and tested |
Wayland can provide a modern isolation and rendering model, but results depend on the compositor, graphics driver, Xwayland, portals, and applications. Xorg has broader legacy compatibility but also retains the X11 security and architecture model. Neither label alone establishes that a complete workstation requirement is met.
Establish a small Xorg test #
Install Xorg only after the correct graphics module works:
# pkg install xorg
Confirm that the intended login is a member of video, start a fresh login session after any group change, and use a small window manager or the selected desktop’s documented startx procedure. The desktop baseline guide
uses XFCE as one bounded Xorg test.
If the server exits, inspect its log before generating configuration:
$ grep -E '\(EE\)|\(WW\)' $HOME/.local/share/xorg/Xorg.0.log
Some launches write /var/log/Xorg.0.log instead. Read the file that was modified by the failed attempt. Modern Xorg usually discovers the KMS device, monitor, and input devices without a monolithic xorg.conf.
Establish a small Wayland test #
The current FreeBSD Wayland chapter uses the wayland and seatd packages as the common base:
# pkg install wayland seatd
# sysrc seatd_enable=YES
# service seatd start
The selected compositor may install these as dependencies and has its own startup requirements. The seatd service provides non-root access to shared devices for the standalone compositors described in the FreeBSD Wayland chapter; a desktop with its own documented seat management can have a different boundary. The login needs access to graphics and input devices, and the official procedure places it in the video group. A GENERIC kernel includes evdev support, while a custom kernel must preserve it.
Install one compositor or one desktop Wayland session and start it from a virtual terminal first. Keep the terminal output. Do not enable a graphical login manager until the manual session starts consistently.
Install Xwayland when required by applications that do not support Wayland natively:
# pkg install xwayland
The compositor controls how Xwayland starts. A running Xwayland process proves compatibility support is present, not that every X11 application behaves identically.
Identify the active session #
Within a graphical terminal, inspect the session variables:
$ echo "$XDG_SESSION_TYPE"
$ echo "$DISPLAY"
$ echo "$WAYLAND_DISPLAY"
A native Wayland session normally has a WAYLAND_DISPLAY; Xwayland clients also receive a DISPLAY. An Xorg session normally has DISPLAY without WAYLAND_DISPLAY. Applications can still choose a backend independently, so use application diagnostic output when backend choice matters.
Test the boundary cases #
Before making a display manager start the session automatically, test:
- login, logout, and return to a usable virtual terminal;
- all attached displays, hotplug, resolution, rotation, and scaling;
- keyboard layout, pointing devices, and accessibility input;
- browser rendering, audio, camera access, and screen sharing;
- suspend and resume on portable systems;
- X11-only applications under Xwayland if Wayland is selected;
- the actual remote-access method, not merely local rendering.
Keep the desktop or compositor package, graphics package, FreeBSD release, and package branch with the result. These versions are necessary when a later package upgrade changes behavior.
Change stacks without obscuring the result #
Disable an existing display manager before enabling another. Test the replacement manually, then change the startup setting in one transaction. Retain a virtual-terminal login and the commands needed to disable the graphical manager if it loops or presents a black screen.
Do not keep adding desktop environments to diagnose one failed session. Each environment adds services, session files, portals, and application defaults. A small known-working baseline makes the failed layer visible.