Synopsis #
A maintainable desktop starts with one verified graphics driver, one display stack, and one desktop session. Installing several desktops and enabling a display manager in the first transaction hides whether a failure belongs to the kernel driver, Xorg or Wayland, session startup, D-Bus, or the login manager.
This procedure uses XFCE started manually through Xorg as a diagnostic baseline. It is not a universal desktop recommendation and does not establish that every graphics processor, display, or laptop function works. Complete the hardware preflight and graphics driver setup first. Select another maintained environment when its requirements better fit the system.
Keep the package source coherent #
Confirm the configured repositories and update their metadata:
$ pkg repositories
# pkg update
Install Xorg, XFCE, and the D-Bus service used by the desktop:
# pkg install xorg xfce dbus
Do not switch package branches during desktop diagnosis. If a package-source policy has not been chosen, read the packages, ports, and poudriere guide first.
Prepare the login session #
Confirm the intended login’s supplementary groups:
$ id
Add it to video if the graphics setup requires that group, substituting the real login name:
# pw groupmod video -m loginname
End the existing login session and log in again after changing groups.
Enable and start D-Bus:
# sysrc dbus_enable=YES
# service dbus start
Create or inspect $HOME/.xinitrc. Preserve any existing configuration. For a new XFCE baseline, its content is one line:
. /usr/local/etc/xdg/xfce4/xinitrc
The file belongs to the unprivileged login, not to root.
Start the session manually #
From a virtual-terminal login as the desktop user, run:
$ startx
A successful session should reach XFCE, permit logout, and return to a usable terminal. Test keyboard and pointing devices, open a terminal, and inspect the active display and session variables.
If startx fails, retain all terminal output and inspect the Xorg log:
$ grep -E '\(EE\)|\(WW\)' $HOME/.local/share/xorg/Xorg.0.log
The log may instead be /var/log/Xorg.0.log. Resolve kernel-driver attachment, device permissions, or an explicit Xorg error before adding a display manager.
Add one capability at a time #
After the baseline starts repeatedly, add workstation functions in an order that preserves useful diagnostics:
- Install one browser and test rendering.
- Verify audio output and input outside and inside the browser.
- Configure and test a webcam before a meeting application.
- Test removable and application-specific devices using scoped USB permissions .
- On a laptop, complete Wi-Fi and suspend tests .
- Separate locale, keyboard, and time-zone configuration from desktop-specific input settings.
- Select and test one printing stack only when printing is part of the required workload.
- Treat a Windows application as a separate compatibility decision using Wine , not as proof that the desktop baseline failed.
Install applications through the chosen package source. Avoid copying Linux desktop service instructions unless the corresponding service and paths are documented for FreeBSD.
Add a graphical login only after the baseline works #
The FreeBSD desktop chapter documents LightDM as an XFCE display-manager option:
# pkg install lightdm lightdm-gtk-greeter
# sysrc lightdm_enable=YES
Reboot during a controlled test or start the service from a virtual terminal. Keep a root shell or another virtual-terminal login available until LightDM has completed login and logout successfully.
If the manager fails, disable it from a text console:
# sysrc lightdm_enable=NO
# service lightdm stop
Do not enable two display managers. Their rc services and session selection can conflict even when both packages install successfully.
Choose a different desktop deliberately #
Plasma, GNOME, MATE, Cinnamon, and LXQt are available through FreeBSD packages, but their service, filesystem, display-manager, and Wayland requirements differ. Follow the current FreeBSD desktop chapter for the selected environment rather than adapting the XFCE line mechanically.
When Wayland is required, use the Xorg or Wayland decision guide and the selected compositor’s documented startup procedure. Keep this Xorg baseline only if it remains useful as a recovery or comparison environment; otherwise remove unused desktop packages after the replacement is proven.
Maintain the result #
Record the FreeBSD release, package branch, graphics module, desktop package, and display manager. Review package upgrade transactions before accepting them, especially when they replace graphics, Xorg, compositor, or desktop packages. After a material upgrade, test login, browser, audio, external displays, and suspend before the next maintenance window closes.