You Got A Question? Ask    GNOME Community!

Creating GTK+ Themes & Maintain Them Over Time


The default Theme of GTK+ is called Raleigh (above figure) and the name comes from Red Hat Headquarters in Raleight (North Carolina), were 4.500 out of 6100 Red Hat employees are working at.

Adwaita is the default theme for GNOME and it means “The only One” in Bengali.

Creating a GTK+ Theme from Scratch

This isn’t a guide how to create a GTK theme, but some tips primary focused on how we can maintain compatibility in our themes when new GNOME versions are releasing. Theme authors are quitting theming because they cannot port their themes on the newer versions of GNOME.

This is both a fault of GNOME that doesn’t provide documentation for their CSS properties and pseudo-classes, plus a fault of authors which ignore the problem and they can’t deal with it later on.

1. Get Adwaita Default Theme

Never ever hack on someone’s else theme. Their bugs (there are bugs!) will also become yours, and it will be really hard to track them. Always download the default Adwaita and use it as your base. Get if from download server:

Or clone it from

Clean up the theme (remove the files you don’t need) and fix the main CSS files.

2. Apply Version Control

Place your theme in a directory



and initialize a new git. That will help you to track the changes you made, but most importantly you will use it as a pattern to create more themes.

Deploy it on Github!

3. Use Your Theme Daily

The only way to find out the bugs and misses is by using your theme daily. Link your development theme to


& (for GTK2)


4. Use A Good Editor For Editing Stylesheets


GEdit has a plugin for creating GTK3 Themes called Gedit-Cossa. Cossa is apparently broken on Fedora 20, so I go with Brackets. I prefer Brackets anyway. It is an awesome editor, plus it will help you in many more projects so it is a worth to learn using it.

5. Don’t Use Engines

Stay as close as possible to the upstream. Don’t use engines on GTK2 themes. Personally, I wouldn’t get bothered much with GTK2.

Just let the default Adwaita to handle GTK2, till you complete GTK3 and then spend some time on it.

6. Create Variations

Don’t create more themes than what you can really manage. Try to break CSS files on smaller parts and create different variations of your theme on different git branches.

That will reduce significantly portability to the newer versions of GNOME for all your themes.

7. Use Parasite & Widgets Factory


Use GTK Parasite and Gtk3-Widget-Factory to inspect GTK2 components and for live editing your changes. Another good testing is to check your theme on gtk3-demo application.

Remember: Some modules (eg Nautilus Gedit) have their own CSS files.

8. Track GTK Changes On GNOME.Next

This is tricky. You should watch the changes on GNOME-Themes-Standard, but sometimes there are changes that might don’t belong there, like this one.

Additionally you can create two clean clones of Adwaita 3.12 & 3.14 , apply 3.14 to 3.12 and see the changes.

9. Shipping The Theme

Don’t waste energy to make installation scripts or PPAs, it has not real benefits. Just zip the files the theme needs and upload it on Deviant Art and GNOME Look (for now!). Keep zip clean, don’t include more files than necessary, or editing instructions. Users don’t appreciate those.

Remember. You created branches for this reason. Ship your variations as different themes!

10. Release Soon, Update Often!

Did you make just a tiny tiny change? Release it!

Please try to keep a smart versioning. For example your major version, plus the date,


version 3.20140423
version 3.20140424 (minor)
version 3.1.20140425 (average - avoid this!)
version 4.20140425 (big - new GNOME version support / new variation / something important)

Finally add changelog with user-readable changes, a short description of the theme (plus d/l URLs) and your personal info, inside a text file.

Don’t forget to include what GNOME version your themes support!

11. Develop For GNOME.Next

Don’t use Virtual Machines for porting your themes to the next GNOME release (e.g GNOME 3.13.x). Use JHBuild! This is very essential, GTK is going to bring major changes, you should always be updated (3.13.92 / beta) before the final GNOME release!

You got a new theme? Review it, add some screenshots and email it to us at We are happy to publish it!

  We can't watch comments unless G+ provides an API or if you send a notification, e.g +World Of Gnome
     Sometimes is better to place your questions on GNOME Community
  • Tommy Brunn

    Why wouldn’t you create a PPA or similar? How else would you make sure that users are using the latest version of the theme? I mean, sure, some users might clone the repo, symink it into the correct directory and pull every now and then, but 99% won’t.

    • alex285

      1. Who user would want 10 repos for just 10 themes?
      2. Authors don’t support every distro anyway (too much work.). All or none.
      3. Repos can significantly increase update time, and they cause issues from time to time (eg broken repos, it happens)
      4. Repos install themes system-wide. Really?
      5. Soon enough I will release a theme service, so no need for repos anyway.

      • Tommy Brunn

        1. Probably none, but for now it’s the best solution we have. With gnome-look and deviantart, there are no updates whatsoever.
        2. You state “all or none” as if it was an axiom. You can certainly choose to support only a few distros. Users of other distros can clone the repo or download a tarball from github or whatever. If you’re manually building packages, you’re doing it wrong, so there’s not really any significant extra effort when releasing new versions.
        3. And gnome-look and deviantart could go down. Yes, of course there can be problems. Most of the time there aren’t any, however.
        4. I agree that that’s maybe not ideal. Most of the time it’s no big deal though. What are the chances that two users on the same installation will want to use two different versions of the same theme? Very slim, I’d say.
        5. Okay, that could be good.

        • alex285

          1. What are the chances that people want to use the repo anyway, except if they love your theme so much. Which is hard, coz we taint to change themes.

          But even if that is the case, they just can check on it for updates periodically.

          2. Actually this goes to point one. A repo that would include most of the themes would be better. They can do it.

          4. I am not talking about multi-seating. But it is just themes, why should be system-wide installed? Personal preferences belong to user not to system.
          Anyway personally I prefer even my programs to be user-specific installed :)

      • bot

        noobslab maintains a PPA for themes.Unfortunately there is no copr repo for fedora.Either a single large repo or few grouped repos can be made.