GTK2 and 3 both use theme to control the appearance of applications that use them. While an application can override the theme settings in various ways, there are also per-user (and even per-application) ways to customize their appearance and behavior.


For GTK2, theme config files normally reside in $XDG_DATA_DIRS/themes/theme-name/gtk-2.0/, so something like /usr/share/themes/theme-name/gtk-2.0/. The main configuration file is gtkrc, with subsidiary files in styles/. It’s worth taking a browse through the gtkrc of your favorite theme, to get a feel for how things work.

Per-user, the gtkrc can be overridden/augmented with the settings in ~/.gtkrc-2.0. This file is loaded after the gtkrc for your current theme, so it only needs to specify settings that are different. E.g., mine looks like

# Add steppers to scrollbars
style "scrollbar-style" {
    GtkScrollbar::has-backward-stepper = 1  
    GtkScrollbar::has-forward-stepper = 1
class "GtkScrollbar" style "scrollbar-style"

# Make sure scrollbars don't warp on click
gtk-primary-button-warps-slider = 0

Note that the method described below, for GTK3, will also work for GTK2: you can create a custom theme in ~/.themes/, import the main theme, and then it will be used in place of it.

Also note that in GTK2 the rc file covers both appearance and behavior. E.g., you can use it do to things like create or override keyboard shortcuts, etc.


GTK3 themes live in $XDG_DATA_DIRS/themes/theme-name/gtk-3.0/, but now there are several files to look at: settings.ini contains various behavior settings. Then there are probably a bunch of *.css files; GTK3 loads gtk.css, which usually imports a bunch of other files that touch on specific aspects of the system.

If you want to override settings.ini, just put your own in /.config/gtk-3.0/; this file will be loaded after the theme’s settings, so anything you do here will replace the theme’s settings. Mine looks like

gtk-primary-button-warps-slider = false

Changing settings in the .css files is a bit more tricky. You can create ~/.themes/theme-name/gtk-3.0/gtk.css but if this file exists the main theme file will not be loaded at all. So you can’t just put your changes in it, or every GTK3 application will load with a mostly empty theme. Instead, import the main gtk.css theme you prefer to use at the top of your file, and then add any customizations below it. E.g., here’s what mine looks like:

/* Load the original theme */
@import url("/usr/share/themes/Mint-X/gtk-3.0/gtk.css");

/* Override scrollbar setting */
.scrollbar {
    -GtkScrollbar-has-backward-stepper: 1 !important;
    -GtkScrollbar-has-forward-stepper: 1 !important;

Supposedly you can also place a settings.ini in the same directory as your customized theme and it will be picked up.

Per-application customization

Both GTK2 and 3 will try to load some aspects of their theme from files specified in environment variables, if they are set. You can use this to override parts of the theme, or switch to a different theme entirely, on a per-application basis.

For GTK2, the variable GTK2_RC_FILES, if set, will cause all files in the colon-separated list to be loaded as if they were gtkrc files, in order. I believe that this overrides your per-user file as well, so if you want any per-user settings to be applied, you’ll have to add $HOME/.gtkrc-2.0 to the list, probably at the end.

For GTK3, GTK_THEME specifies the gtk.css file to be loaded. You can use this to either switch to a different theme entirely, or create your own gtk.css as above that imports a theme and then overrides a few settings. I’m not sure if there is a way to override settings.ini on a per-app basis.

For GTK3, it’s possible to discard themes entirely and go with the default (ugly) theme, by unsetting GTK_DATA_PREFIX. E.g.,

GTK_DATA_PREFIX= my-application &


  • Resource files: GTK+2 Reference Manual – Describes where resource (rc) files are found, their format, etc. Unfortunately, there does not appear to be a quick and easy reference to all possible per-widget settings.

  • GTK+ CSS: GTK+ 3 Reference Manual – Reference to the CSS used in GTK3.

  • Bindings: GTK3 – Reference to the CSS used for assigning key bindings to widgets.

  • GtkCssProvider: GTK3 – Describes what CSS files GTK3 will try to load at startup, and in what order.

  • Settings: GTK3 – Describes the paths GTK3 will search for settings.ini files. Note that the settings themselves are generally described in the documentation for the widgets to which they apply.