How Linux Propagates Dark Mode Preferences

In modern Linux operating systems, propagating a dark mode preference across various desktop environments, UI toolkits, and sandboxed packaging formats relies on a standardized, decoupled architecture. Historically fragmented by competing toolkit-specific configurations, the ecosystem has converged on the XDG Desktop Portal specification. This article outlines how a user's color scheme choice moves from desktop environment settings daemons across D-Bus interfaces to natively update GTK, Qt, web browsers, and sandboxed applications in real time.

The Modern Standard: XDG Desktop Portal

The core mechanism for color-scheme switching across contemporary Linux distributions is the org.freedesktop.portal.Settings D-Bus interface, developed under the Flatpak and FreeDesktop initiatives.

Within this interface resides the org.freedesktop.appearance namespace, which exposes the color-scheme key. This key accepts three standardized unsigned integer values:

• 0: No preference (defaults to light mode in most implementations)
• 1: Prefer dark appearance
• 2: Prefer light appearance

When a user toggles dark mode in their system settings, the Desktop Environment (DE) updates this property via D-Bus, broadcasting a SettingChanged signal to all running processes listening to the portal interface.

Desktop Environment Implementation

Different desktop environments trigger this D-Bus change through their specific internal configuration backends:

• GNOME: Toggling the dark style in the GNOME Control Center updates the GSettings key org.gnome.desktop.interface color-scheme to 'prefer-dark'. The GNOME desktop portal implementation (xdg-desktop-portal-gnome) watches this key and immediately reflects the state on the org.freedesktop.portal.Settings interface.
• KDE Plasma: Changing the system theme or color scheme in Plasma updates configurations in ~/.config/kdeglobals. The xdg-desktop-portal-kde daemon monitors these configuration changes and synchronizes the portal's color-scheme property accordingly.

Because desktop environments implement their own portal backends, the overarching frontend daemon (xdg-desktop-portal) can serve uniform data regardless of whether the session is running GNOME, KDE Plasma, Sway, or another compositor.

How Toolkits and Runtimes Consume the Preference

Once the D-Bus signal is emitted, client applications consume the preference through toolkit-level abstractions:

GTK 4 and Libadwaita

Modern GTK 4 applications using libadwaita subscribe directly to the portal interface. When the SettingChanged signal is received, AdwStyleManager dynamically switches the stylesheet from the default light variant to the dark variant without requiring an application restart.

Qt (Qt 6.5 and Newer)

Beginning in Qt 6.5, the Qt platform abstraction (QPA) natively queries the XDG Settings Portal on Linux. When the portal reports a dark mode preference, Qt adapts its base palette—specifically the text and window roles—allowing applications utilizing standard palettes to adopt dark aesthetics seamlessly.

Web Browsers and Electron

Web browsers such as Chromium and Mozilla Firefox, along with Electron-based applications (like VS Code, Discord, and Slack), query the portal directly via D-Bus. When the portal signals a change, the browser updates its internal state, toggles the browser chrome, and sets the CSS @media (prefers-color-scheme: dark) media query to true, which in turn triggers dark styling on supported websites.

Sandboxed Applications (Flatpak and Snap)

One of the primary drivers behind the XDG Desktop Portal standard was container isolation. Sandboxed formats like Flatpak and strictly confined Snaps block applications from directly reading arbitrary host configuration files, such as ~/.config/gtk-3.0/settings.ini or host dconf databases.

Instead, the sandbox punches a controlled opening to the D-Bus session bus, letting the app communicate directly with xdg-desktop-portal. This architecture ensures that sandboxed apps receive real-time color scheme notifications identically to unsandboxed native apps.

Legacy Applications and Fallbacks

Legacy toolkits, including GTK 2, GTK 3, and older Qt versions, do not natively monitor the Freedesktop color-scheme portal. For these applications, desktop environments and compatibility tools employ fallback layers:

1. GTK 3 Fallbacks: Many desktop settings managers update the GSettings key gtk-theme to a dedicated dark theme (such as Adwaita-dark) simultaneously with the color-scheme portal key. GTK 3 applications read this value through the xsettings daemon or local configuration files.
2. Environment Variables: Some users and wrappers rely on setting GTK_THEME or QT_STYLE_OVERRIDE to force specific dark styles, although this method is static and cannot update running processes on the fly.
3. Third-Party Daemons: In custom or lightweight window managers (such as i3 or bspwm), utility scripts monitor portal states or expose mock portals (like xdg-desktop-portal-wlr) to relay theme switching down to config files and running apps via custom commands.