Modern GNOME is not the old GTK theme playground with a new coat of paint. GNOME Shell, GTK 3 applications, GTK 4 applications and libadwaita applications are four different surfaces. A theme selected in Tweaks can change one or two of them and leave the rest untouched. That is expected behavior, not necessarily a broken package.
The three diagrams in this article are documentation-based illustrations, not desktop screenshots. Official screenshot assets could not be fetched reliably while preparing the article, so every image is explicitly marked “STYLISED MOCKUP / 示意图”.
First question: which layer are you changing?
| Layer | What it controls | User path / entry |
|---|---|---|
| GNOME Shell | Top bar, overview, dash, notifications and quick settings | Shell stylesheet; custom themes require an extension |
| libadwaita apps | Current GNOME application widgets and adaptive layouts | Built-in Adwaita styles plus light/dark, accent and contrast APIs |
| GTK 4 apps | Toolkit widgets not necessarily using libadwaita | Application or toolkit CSS |
| GTK 3 apps | Older native applications and many third-party tools | ~/.local/share/themes/<name>/gtk-3.0/ |
| Icons and cursors | Freedesktop icon and Xcursor themes | ~/.local/share/icons/ |
| GDM | The login screen | System component; separate from the logged-in Shell |
When a newly installed theme changes only half the desktop, that is usually not a bug. It means you installed one layer. Icons, window decorations, application controls and the desktop shell commonly have different owners.
A customization order that is easy to undo
- Use Settings → Appearance first. Light/dark mode, accent color, wallpaper and contrast are the supported system-wide controls.
- Install GNOME Tweaks for icon, cursor and legacy GTK choices. Treat it as an extra control panel, not a promise that libadwaita applications will accept arbitrary themes.
- Install the User Themes extension before selecting a GNOME Shell theme. A shell package normally contains a gnome-shell/gnome-shell.css subtree.
- For visual consistency, use adw-gtk3 to make legacy GTK 3 applications resemble libadwaita, rather than trying to force libadwaita into an old GTK theme.
- Test one native app, one Flatpak and the Shell after every change. Their theme visibility and sandbox rules differ.
Inspect and switch settings from the terminal
The GUI is good for discovery; commands are good for repeatability. The examples below affect only the current user. Confirm that every theme name exists locally before applying it.
# supported light/dark preference
gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
# icon and cursor themes
gsettings set org.gnome.desktop.interface icon-theme 'Papirus-Dark'
gsettings set org.gnome.desktop.interface cursor-theme 'Bibata-Modern-Ice'
# User Themes extension: select a Shell theme
gsettings set org.gnome.shell.extensions.user-theme name 'MyShellTheme'Do not begin by copying everything into a system directory with sudo. A user-local install is easier to remove and will not leave unmanaged files mixed into distribution packages.
If you are editing a theme, change one thing first
Copy an existing theme into the user directory and give it a new internal name. Do not edit the distribution copy under /usr/share. For the first pass, change one color, one spacing value or one icon group. Once the loader path and cache behavior are proven, widen the edit.
If the package has metadata or an index.theme, update its internal name as well. Renaming only the directory can create two identically named entries and leave inheritance pointing at the original package.
Version changes: why old guides fail
| Version | Theme-relevant change |
|---|---|
| GNOME 3 / GTK 3 | The classic third-party theme model: GTK themes in ~/.themes, Shell themes through User Themes, and Tweaks tying the choices together. |
| GNOME 40 | Redesigned the overview around horizontal workspaces. The visual break was obvious, while the larger technical change was the move toward GTK 4. |
| GNOME 42 and libadwaita | Many core apps adopted libadwaita. Arbitrary distro and user GTK themes stopped being a reliable way to restyle those apps. |
| GNOME 47–50 | Accent colors, high-contrast handling and light/dark integration improved. GNOME 50 also completes the move to a Wayland-only desktop session; X11 apps still run through Xwayland. |
A path from an old guide may still exist while the theme engine, toolkit generation or display server has changed underneath it. Before following a recipe, identify whether it targets GTK 2/3/4, Qt 5/6, X11 or Wayland, then check its date.
Common failure modes
- Do not copy a random gtk.css over libadwaita resources and expect updates to be safe. Minor widget changes can make text unreadable.
- A Shell extension must match the installed GNOME Shell version. Disable incompatible extensions before a major upgrade.
- Flatpak applications cannot automatically see every host theme. Prefer matching runtime theme extensions or supported color-scheme portals.
- Changing GDM requires system files and affects the login path. Keep it outside an ordinary per-user theme experiment.
A sensible end state
Tune the default theme until it is comfortable, then replace one third-party component at a time. A complete makeover is satisfying, but it makes readability, scaling and Flatpak mismatches harder to diagnose. The durable setup is often conservative: keep the desktop’s default widget style and change colors, icons, cursors and window decoration around it.
More desktop theming guides
- KDE Plasma theming guide
- Xfce theming guide
- Cinnamon theming guide
- MATE theming guide
- LXQt theming guide
Comments