How to edit themes in Gnome 40+ - Tutorial

Updated: March 25, 2022

You can't edit Gnome themes, no more, someone wrote me in an email. And I replied, what what. The person pointed out that the instructions I laid out in my Gnome theme edit guide no longer worked. Specifically, the gtk.css file, which is supposed to contain the necessary clauses to make theme changes, like font color for instance, simply weren't there anymore.

I decided to explore this further. I powered on CentOS 9 Stream, which comes with a modern version of the Gnome desktop environment, and I looked what gives under the Adwaita theme folder. Indeed, the old method of customization seems no longer applicable. Which is why we need this tutorial. Begin, we must.


Problem in more detail

Anyway. Go to /usr/share/themes/Adwaita, and see what's under this directory tree. In the gtk-3.0 subfolder, there is a gtk.css file, but it's empty. It's a stub that reads the following:

/* Adwaita is now part of GTK+ 3, this file is no longer used */

So, we need something else.

The new way of editing Gnome themes

All right. The method required to edit Gnome 40+ themes is quite complex and convoluted, but then again, the fact you need to manually tweak CSS files is already a big problem. Then again, the only desktop in the Linux space that lets you do things GUI way, without any hackery, is Plasma. However, I don't want to get philosophical or fanboyish here. The purpose of this tutorial is to show you how to edit Gnome themes, for whatever reason. Like say font color, although Adwaita has decent defaults (unlike most Linux themes in general).

1. Clone the gtk repository from GitLab

This is the first thing:

git clone

2. Switch to the "older" branch of this tree

We need this so we can edit GTK 3.X themes - the current branch is for GTK 4.0, and there, the handling of theming is different. Now, this means that sometime in the future we will have to face yet another technical obstacle, but that's a different story altogether - in fact, there might already be programs that will not be using any of your custom theming, and other issues of this nature. But let us progress slowly.

git checkout gtk-3-24
Branch 'gtk-3-24' set up to track remote branch 'gtk-3-24' from 'origin'.
Switched to a new branch 'gtk-3-24'

Here, you will now see a list of files, including "source" CSS files from which themes are built.

Theme directory

3. Edit the colors file

Open _colors.scss in a text editor. What you will see is the familiar theme syntax we saw in the past, and we now need to make changes, like say font color.

// When color definition differs for dark and light variant
// it gets @if ed depending on $variant

$base_color: if($variant == 'light', #ffffff, lighten(desaturate(#241f31, 100%), 2%));
$text_color: if($variant == 'light', black, white);
$bg_color: if($variant == 'light', #f6f5f4, darken(desaturate(#3d3846, 100%), 4%));
$fg_color: if($variant == 'light', #2e3436, #eeeeec);

$selected_fg_color: #ffffff;
$selected_bg_color: if($variant == 'light', #3584e4, darken(#3584e4, 20%));
$selected_borders_color: if($variant== 'light', darken($selected_bg_color, 15%), darken($selected_bg_color, 30%));

What you need to change depends entirely on your needs. But let's say text. Look at the second uncommented line in the file. At the moment, it reads:

$text_color: if($variant == 'light', black, white);

We will change this to:

$text_color: if($variant == 'light', red, white);

The structure of the line is in the form of IF THEN clause, which means that if the theme is light, the first argument after the comma will be used, and if not, then the second. In other words, if it's a light theme, the text color declaration will be set to black. For the dark Adwaita theme, it will be white. We will change the black font color to red.

4. Parse the file

The next step is to "build" the final theme gtk.css file. This is done using the script. It's somewhat like building the GRUB menu from a variety of "source files" instead of directly editing the menu. This is a modern way of doing things, and while more modular, it's also more annoying.

Run the script. You may see an error:

sassc needs to be installed to generate the css.

This means you need to install the sassc program (utility) from the repos. The exact procedure to do this will differ from distro to distro, i.e., the actual system you're working on. In CentOS 9 Stream, this was extra complicated as sassc is not available in the standard repos, and I had to enable EPEL to get the tool installed. Now, alternatively, I could have done this on a Fedora box or an Ubuntu box. Anyway.

After some repo fiddling, the utility is there, and we run it:

Generating the css...

The script will create two files, gtk-contained.css and gtk-contained-dark.css, to be used with the light and dark themes, respectively.

-rw-rw-r--. 1 roger roger   4338 Mar  8 15:49 _colors.scss
drwxrwxr-x. 3 roger roger   4096 Mar  8 15:49 .
-rw-rw-r--. 1 roger roger 171713 Mar  8 15:53 gtk-contained.css
-rw-rw-r--. 1 roger roger 171416 Mar  8 15:53 gtk-contained-dark.css

5. Copy the created CSS file to your theme

Now, we need to actually grab the CSS files we generated (and a few other files) and use them in our custom theme. We will copy the default Adwaita theme to the home directory, and then copy the CSS in. I also took the liberty of editing the copied theme name (in the index.theme file) so it's easier to distinguish from stock Adwaita. I called mine Adwaita-2.

cp -r /usr/share/themes/Adwaita ~/.themes/Adwaita-2
gedit ~/.themes/Adwaita-2/index.theme

Name the theme whatever.

cp -r [local cloned git repo location]/gtk/gtk/theme/Adwaita/assets ~/.themes/Adwaita-2/gtk-3.0/
cp -r [local cloned git repo location]/gtk/gtk/theme/Adwaita/gtk-contained.css ~/.themes/Adwaita-2/gtk-3.0/gtk.css

In essence, we are overwriting the empty stub file.

6. Activate the new theme

Now, launch Gnome Tweaks and activate your new theme:

Select new theme

Theme changed

And there you go! Job done. It only took 16 minutes and 6 easy steps. Right? Right.


Hacking themes on the command line is very 1998, but then, a lot of the Linux desktop experience remains 1998, unfortunately. Not a good thing, especially if people are seeking to leave the world of Windows behind them, present company included. But then, we managed to complete our tasks, so, it ain't all bad.

If you need to make theme edits in Gnome 40+, you will need to clone the original repository, switch to the old branch, make changes to the color declarations, build the CSS files, and then copy them over in your own theme. Not trivial, but doable. And totally avoidable if distros commit to shipping their products with beautiful, clear, crisp, sharp fonts. Until then, hopefully, you will find this article useful. Lastly, all of this may soon change yet again, because GTK-4.0 and libadwaita bring their own theming problems. See you around.