The Handbook

    Theme
    • Guides
        • Check a system before installing FreeBSD
        • Orient a Linux administrator on FreeBSD
        • Supported FreeBSD releases
        • Choose a FreeBSD documentation and support channel
        • Move files safely without GNU mv -t
        • Update and Upgrade FreeBSD
        • Upgrade 14.4 or 15.0 to FreeBSD 15.1
        • Choose packages, ports, or poudriere
        • Choose the quarterly or latest package branch
        • Choose a FreeBSD download or package mirror
        • Convert a test installation to pkgbase
        • Make a system setting persistent
        • Run a command from cron reliably
        • Configure locale, keyboard, and time zone
        • Configure a serial console for recovery
        • Choose a custom kernel, module, or loader setting
        • Run a Linux binary with the compatibility layer
        • Check desktop and laptop hardware before installation
        • Choose and check a graphics driver
        • Choose Xorg or Wayland
        • Build a maintainable desktop baseline
        • Install and check a desktop browser
        • Install GNOME and troubleshoot graphical login
        • Check laptop Wi-Fi, power, and suspend
        • Check multimedia readiness
        • Choose and configure a printing stack
        • Run Windows applications with Wine
        • Snapshot and replicate a ZFS dataset
        • Choose a filesystem and storage layout
        • Operate ZFS without losing the recovery path
        • Restore files from a ZFS snapshot
        • Find what is using ZFS space
        • Grow a ZFS virtual disk
        • Read ZFS pool health and run a scrub
        • Replace a failed device in a ZFS mirror
        • Replicate a ZFS dataset over SSH
        • Test changes in a writable ZFS clone
        • Read a ZFS pool from another FreeBSD system
        • Change PF safely on a remote host
        • Configure a narrow WireGuard tunnel
        • Share a directory with NFS
        • Share files with a named Samba account
        • Plan a FreeBSD home server
        • Choose a mail server or an outgoing relay
        • Publish a network service safely
        • Choose a jail network model
        • Choose native jails or a jail manager
        • Choose a jail or a bhyve virtual machine
        • Establish a FreeBSD security baseline
        • Choose a MAC policy
        • Audit security-relevant activity
        • Start a DTrace performance investigation
    • Integrations
        • Create a first jail with Bastille
        • Compare jail managers and OCI tooling
        • Publish a Bastille service through PF
        • Mount a ZFS dataset in a Bastille jail
        • Update and upgrade Bastille jails
        • Back up and restore a Bastille jail
        • Prepare bhyve and vm-bhyve
        • Install a Linux guest with vm-bhyve
        • Choose NFS or Samba for file sharing
        • Choose ZFS backup automation
        • Build a first signed poudriere repository
        • Operate a signed poudriere repository
        • Manage FreeBSD configuration with Ansible or Salt
        • Run Motion with webcamd on FreeBSD
        • Design a reverse proxy, certificates, and monitoring
    • FAQ
      • Troubleshooting
          • Recover an interrupted freebsd-update run
          • Resolve a package repository or ABI mismatch
          • Diagnose the FreeBSD boot path
          • Recover with a ZFS boot environment
          • Diagnose DNS, routing, and firewall paths
          • Diagnose network mbuf exhaustion
          • Bind a service to a low port without running it as root
          • Diagnose a service that will not start
          • Diagnose audio output or input
          • Diagnose webcamd, cuse, and a webcam
          • Fix USB device permissions without opening every device
      • About this handbook
      • Synopsis
      • Install and enable the services
      • If the login screen does not appear
      • If login returns to the greeter
      • References

      Install GNOME and troubleshoot graphical login

      Last reviewed
      21 November 2026
      Applies to
      15.1-RELEASE
      Tested on
      15.1-RELEASE

      Synopsis #

      GNOME provides the desktop session; GDM provides graphical login. Both depend on working graphics and system services. Configure the graphics driver first, and keep a text console or SSH session available while testing.

      Use a normal user account for the desktop.

      Install and enable the services #

      Install the minimal desktop, display manager, and Xorg:

      # pkg install xorg gnome-lite gdm
      

      Use gnome instead of gnome-lite for the larger set of GNOME applications. If the graphics driver requires membership in video, grant access to both the desktop user and GDM:

      # pw groupmod video -m loginname
      # pw groupmod video -m gdm
      

      Replace loginname with the actual account and log in again after changing its groups.

      Prepare the user’s Xorg session, replacing loginname with the actual account. As that user, copy the packaged session initialization file; merge it with an existing .xprofile rather than overwriting custom settings:

      $ cp /usr/local/share/examples/gnome-shell/xprofile ~/.xprofile
      

      As root, create the account-settings directory if needed:

      # install -d /var/db/AccountsService/users
      

      Create or update /var/db/AccountsService/users/loginname:

      [User]
      Language=en_US.UTF-8
      Session=gnome-xorg
      SystemAccount=false
      

      Use the user’s preferred locale. The installed GNOME 47 packages support the gnome-xorg session; select GNOME on Xorg at login.

      GNOME needs procfs. Add the following line to /etc/fstab if it is not already present:

      proc /proc procfs rw 0 0
      

      Mount it and start D-Bus before GDM:

      # mount /proc
      # sysrc dbus_enable=YES
      # service dbus start
      # sysrc gdm_enable=YES
      # service gdm start
      

      Disable another display manager, such as LightDM, before starting GDM. Do not run both. At the login screen, select the normal user, enter its password, and check that the desktop opens. Log out and back in, then reboot and confirm graphical login still works.

      If the login screen does not appear #

      From SSH or a text console, check the services, procfs, and logs:

      # service dbus status
      $ mount -t procfs
      # pgrep -lf /usr/local/sbin/gdm
      # tail -n 50 /var/log/messages
      # ls -lt /var/log/gdm
      

      Read the current GDM and Xorg logs, rather than an old log from a previous attempt. Driver load failures, unavailable screens, and permissions errors belong to graphics setup . Reinstalling GNOME does not fix those causes.

      If login returns to the greeter #

      Check that the user’s home directory exists, is writable by that user, and has free space:

      $ id
      $ ls -ld "$HOME"
      $ df -h "$HOME"
      

      Run these commands as the affected user. Check its session errors and the GDM logs for the failed login. Do not delete the user’s entire configuration directory as a first step.

      Read the user’s session log if it exists:

      $ tail -n 50 ~/.cache/gdm/session.log
      

      To return to text login while investigating, disable GDM and reboot from the retained administrative session:

      # sysrc gdm_enable=NO
      # shutdown -r now
      

      References #

      • FreeBSD documentation: GNOME
      • procfs(5)
      • Build a desktop baseline with XFCE

      Independent documentation. Not affiliated with or endorsed by the FreeBSD Project or the FreeBSD Foundation.

      Report a bug
      • Synopsis
      • Install and enable the services
      • If the login screen does not appear
      • If login returns to the greeter
      • References