From ArchWiki
Revision as of 08:58, 14 April 2015 by Hoschi (talk | contribs) (add startup location for gtk2)
Jump to navigation Jump to search


From the GTK+ website:

GTK+, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off tools to complete application suites.

GTK+, The GIMP Toolkit, was initially made by the GNU Project for the GIMP but is now a very popular toolkit with bindings for many languages. This article will explore the tools used to configure the GTK+ theme, style, icon, font and font size, and also detail manual configuration.

Configuration programs

These GUI programs allow theme selection and at least customising of a font. They generally overwrite the ~/.gtkrc-2.0 file.

  • LXAppearance — A configuration tool from the LXDE project, which requires no other parts from LXDE or other desktop environment. More flexible customisation than the other programs. || lxappearance
  • gtk-chtheme — Originally derived from GTK+ Theme Switch || gtk-chtheme
  • GTK Theme Switch || gtk-theme-switch2
  • GTK Preference Tool || gtk2_prefs

See also Uniform Look for Qt and GTK Applications#Changing styles in each toolkit.


Note: As ~/.gtkrc-2.0 and other user theme files are not read by other accounts, the custom theme will not apply to X applications run as root. Possible solutions include:
  • Create symlinks, e.g
# ln -s /home/USER/.gtkrc-2.0 /root/.gtkrc-2.0
  • Adjust the theme as root
# gksu lxappearance
  • Use a settings daemon (this is what most desktop environments do). A desktop-agnostic variant using XSETTINGS is available in the AUR under xsettingsd-gitAUR.

GTK+ 1.x

There are a number of GTK+ 1.x themes in the AUR: search for gtk-theme. A good start is gtk-smooth-engineAUR.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size.

Alternatively, use gtk-theme-switch2. Run it with the switch command.

GTK+ 2.x

There are a number of GTK+ 2.x themes in the AUR: search for gtk2-theme. A good start is gtk-engines which includes the popular Clearlooks theme.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size.

Alternatively, GTK+ settings can be configured manually by editing ~/.gtkrc-2.0. A list of GTK+ settings can be found in the GNOME library. To manually change the GTK+ theme, icons, font and font size, add the following to ~/.gtkrc-2.0:

gtk-icon-theme-name = "[name-of-icon-theme]"
gtk-theme-name = "[name-of-theme]"
gtk-font-name = "[font-name] [size]"

For example:

gtk-icon-theme-name = "Tango"
gtk-theme-name = "Murrine-Gray"
gtk-font-name = "DejaVu Sans 8"
Note: The above example requires the packages ttf-dejavu, tangerine-icon-theme, gtk-engine-murrine from the official repositories, and gtk-theme-murrine-collectionAUR from the AUR.

Another example:

# GTK theme
include "/usr/share/themes/Clearlooks/gtk-2.0/gtkrc"

# Font
style "myfont" {
    font_name = "DejaVu Sans 8"
widget_class "*" style "myfont"
gtk-font-name = "DejaVu Sans 8"

# Icon theme
gtk-icon-theme-name = "Tango"

# Toolbar style
gtk-toolbar-style = GTK_TOOLBAR_ICONS
  • The icon theme name is the name defined in the theme's index file, not the name of its directory.
  • If you edit your .gtkrc-2.0 file, only newly started applications will display the changes.

GTK+ 3.x

Note: As of GTK+ 3.14, Adwaita has replaced Raleigh as the default GTK+ theme. See [1].

To start with, you may wish to install the gnome-themes-standard package which provides Adwaita - the standard theme for GNOME with support for both GTK+ 2 and GTK+ 3.

In general, if a selected theme has support for both GTK+ 2 and GTK+ 3, the theme will be applied to all GTK+ 2 and GTK+ 3 applications. If a selected theme has support for only GTK+ 2, it will be used for GTK+ 2 applications and the default GTK+ theme will be used for GTK+ 3 applications. If the selected theme has support for only GTK+ 3, it will be used for GTK+ 3 applications and the default GTK+ theme will be used for GTK+ 2 applications. Thus for application theme consistency, it is best to use a theme which has support for both GTK+ 2 and GTK+ 3.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size. If you use GNOME, use GNOME Tweak Tool: install gnome-tweak-tool. If you use Xfce, use the Appearance tool: go to Settings > Appearance.

If you prefer not to install a theme manager at all, your theme can be set manually in $XDG_CONFIG_HOME/gtk-3.0/settings.ini (this is usually ~/.config/gtk-3.0/settings.ini). An example settings.ini file:

gtk-application-prefer-dark-theme = false
gtk-theme-name = Zukitwo
gtk-fallback-icon-theme = gnome
gtk-icon-theme-name = [icon theme name]
gtk-font-name = [font name] [font size]

A full example of a custom theme as converted from GTK+ 2.x to GTK+ 3.x by lxappearance:

gtk-font-name=Luxi Sans 12

If it still does not change, delete old gtk-3.0 folder in $XDG_CONFIG_HOME and copy gtk-3.0 folder from /path/to/theme to $XDG_CONFIG_HOME. Example:

$ rm -r ~/.config/gtk-3.0/
$ cp -r /usr/share/themes/Zukitwo/gtk-3.0/ ~/.config/  

After this, you need to set the same theme in your DE's appearance configuration tool. There are only a few themes which provide a uniform look for GTK+ 3.x and GTK+ 2.x apps. A few examples:

  1. Adwaita gnome-themes-standard
  2. Vertex vertex-themes-gitAUR
  3. Clearlooks-Phenix clearlooks-phenix-gtk-themeAUR
  4. Newlooks for GTK+ 3 and Clearlooks for GTK+ 2
  5. Zukitwo zukitwo-themesAUR
  6. Numix numix-themes-gitAUR
  7. Ceti ceti-3.14-themeAUR
  8. GreyBird xfce-theme-greybirdAUR
  9. Elegant Brit
  10. Atolm
  11. Hope
  12. OMG

However GTK themes don't work very well across GTK3 releases. At the time of this writing just a handful of themes work as intented.

  • Some themes may require librsvg to display correctly, but not all specify it as a dependency. Try installing it if the chosen theme looks broken.
  • There probably are other themes. Some of these themes are available in the AUR. Also, some of them are not usable as-is for displaying a GTK+ 2.x panel (light text over light background), so you need to use the provided panel background.

You could find what themes installed on your system have both an GTK+ 2.x and GTK+ 3.x version by using this command (does not work with names containing spaces):

find $(find ~/.themes /usr/share/themes/ -wholename "*/gtk-3.0" | sed -e "s/^\(.*\)\/gtk-3.0$/\1/")\
-wholename "*/gtk-2.0" | sed -e "s/.*\/\(.*\)\/gtk-2.0/\1"/

GTK+ and Qt

If you have GTK+ and Qt (KDE) applications on your desktop then you know that their looks do not blend well. If you wish to make your GTK+ styles match your Qt styles please read Uniform Look for Qt and GTK Applications.

GTK+ and HTML with Broadway

The GDK Broadway backend provides support for displaying GTK+ applications in a web browser, using HTML5 and web sockets. [2]

When using broadwayd, specify the display number to use, prefixed with a colon, similar to X. The default display number is 1.

$ display_number=:5

Start it.

$ broadwayd $display_number 

Port Used on default

port = 8080 + ($display_number - 1)

Point your browser to http://localhost:port

To Start apps

$ GDK_BACKEND=broadway BROADWAY_DISPLAY=$display_number <<app>>

Alternatively can set address and port

$ broadwayd --port $port_number --address $address $display_number


Note: See the GtkSettings properties in the GTK+ programming reference manual for the full list of GTK configuration options.

Depending on GTK version, these files are either located in ~/.config/gtk-3.0/settings.ini or ~/.gtkrc-2.0. System settings are applied in etc/gtk-version.

Keyboard shortcuts

Note: This setting is deprecated since GTK 3.10.

Keyboard shortcuts (otherwise known as accelerators in GTK) may be changed by hovering the mouse over the respective menu item, and pressing the desired key combination. To enable this feature, set:

gtk-can-change-accels = 1

GNOME menu delay

Note: This setting is deprecated since GTK 3.10.

This setting controls the delay between pointing the mouse at a menu and that menu opening. This delay is measured in milliseconds.

gtk-menu-popup-delay = 0

Reduce widget sizes

If you have a small screen or you just do not like big icons and widgets, you can resize things easily. To have icons without text in toolbars, use

gtk-toolbar-style = GTK_TOOLBAR_ICONS

To use smaller icons, use a line like this:

gtk-icon-sizes = "panel-menu=16,16:panel=16,16:gtk-menu=16,16:gtk-large-toolbar=16,16\

Or to remove icons from buttons completely:

gtk-button-images = 0

You can also remove icons from menus:

gtk-menu-images = 0

See also [3] and [4].

File-Chooser Startup-Location

Open the gtk-kfile-chooser within the current-working-directory and not with the artifical recent location. Normally the current-working-directory is home-directory.


Modify DConf with gsettings, there is no configuration file:

$ gsettings set org.gtk.Settings.FileChooser startup-mode cwd


Modify ~/.config/gtk-2.0/gtkfilechooser.iniconfiguration file:



Client-side decorations

GTK 3.12 introduced client-side decorations, which move the title-bar away from the window manager. This may present issues such as double title-bars, no title-bar at all or double shadows with compositing enabled.

To remove the shadow and gap around windows (for example in combination with a tiling window manager), create the following file:

.window-frame, .window-frame:backdrop {
 box-shadow: 0 0 0 black;
 border-style: none;
 margin: 0;
 border-radius: 0;

.titlebar {
 border-radius: 0;

.window-frame.csd.popup {
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), 0 0 0 1px rgba(0, 0, 0, 0.13);

.header-bar {
  background-image: none;
  background-color: #ededed;
  box-shadow: none;
/* You may want to use this if you don't like the double title.
GtkLabel.title {
    opacity: 0;

To adjust the buttons in the header bar, use the gtk-decoration-layout setting. [5] The below examples removes all buttons:


cedilla ç/Ç instead of ć/Ć

See [6], and [7] for a workaround using Xcompose (US international layout).

Suppress warning about accessibility bus

If your terminal shows a warning like:

WARNING **: Couldn't connect to accessibility bus:

when running GTK+ 3 programs, you can suppress the warning by executing it like:

NO_AT_BRIDGE=1 theprogram

or by adding NO_AT_BRIDGE=1 to your ~/.bashrc or /etc/environment.

See also