Customizing the GNOME Shell

In this post I will share a modicum of what I have learned to date about customizing the new GNOME 3 Shell. This is based on the GNOME Shell in Fedora 15 Alpha. The good news is that the GNOME Shell is highly configurable. The bad news is that some of this information may become out-of-date quite quickly as the GNOME Shell is still somewhat of a moving target even though it is supposedly close to release.

Here is what the GNOME Shell looks like in Fedora 15 Alpha with all updates applied as of March 23rd 2011:

GNOME3 Shell screenshot

By the way, that is a really beautiful wallpaper! I am glad that cooler heads prevailed and the Fedora Project has finally decided to go with its own custom wallpaper rather than use the default upstream GNOME Shell wallpaper.

Here is what the Applications Overview looks like:

GNOME3 Shell screenshot

Here is what a GNOME terminal window looks like:

GNOME3 Shell screenshot

This is the default theme which, by the way, is called Adwaita. This post will show you how to make the titlebar smaller so that it does not take up so much space on the screen, add back in the minimize and maximize buttons, color the title bars, and more.

GNOME 3 contains some major changes with respect to persistent application settings data. The GConf CORBA-based configuration system is no longer used; it has been replaced by GSettings. GSettings is agnostic about its backend; dconf is merely one backend. Key names are restricted to lowercase characters, numbers and dashes (). Names must begin with a character, must be 32 characters or less in length, must not end with a dash and must not contain consecutive dashes. GSettings stores its schemas in a binary format, unlike GConf which uses XML files. Fedora 14 was the first Fedora release to include GSettings. See the glib-compile-schemas manpage for further information.

A new command line utility gsettings, which replaces gconftool-2, is provided to enable you to easily interface with GSettings.

$ gsettings
  gsettings COMMAND [ARGS...]

  help                      Show this information
  list-schemas              List installed schemas
  list-relocatable-schemas  List relocatable schemas
  list-keys                 List keys in a schema
  list-children             List children of a schema
  list-recursively          List keys and values, recursively
  range                     Queries the range of a key
  get                       Get the value of a key
  set                       Set the value of a key
  reset                     Reset the value of a key
  writable                  Check if a key is writable
  monitor                   Watch for changes

Use 'gsettings help COMMAND' to get detailed help.

$ gsettings list-schemas

$ gsettings list-schemas | grep shell

$ gsettings list-keys

As an example, here is how to enable the digital clock on the top panel to show the date and seconds:

$ gsettings list-keys

# note the failure if you are root!
# gsettings set show-date true
GLib-GIO:ERROR:gdbusconnection.c:2279:initable_init: assertion failed: (connection->initialization_error == NULL)
Aborted (core dumped)

$ gsettings set show-date true
$ gsettings set show-seconds true

Here is how to list all the settings for the GNOME Shell:

$ gsettings list-recursively command-history ['r', 'lg', '?', 'ff', 'lg', 'js', '?', 're', 'r', 'command-history', 'ch', 'lg', 'lgh', 'b', 'r', 'd', 'ff', 'r', 'GSettings', 'GSetting', 'r', 'version', 'ver', 'v'] development-tools true disabled-extensions @as [] disabled-open-search-providers @as [] enable-app-monitoring true favorite-apps ['gnome-terminal.desktop', 'mozilla-firefox.desktop', 'gnome-baobab.desktop', 'gimp.desktop', 'gnome-eog.desktop', 'gnome-screenshot.desktop'] looking-glass-history @as [] show-weekdate false show-date true show-seconds true file-extension 'webm' framerate 15 pipeline ''

While the gsettings utility enables you to modify certain properties of the GNOME Shell, it does not enable you to really customize the current theme. So do not throw away gconftool-2 just yet! There are a whole range of settings that gsettings does not have access to. For instance you can add back the window minimize and maximize buttoms as follows:

gconftool-2 --set /desktop/gnome/shell/windows/buttom_layout --type string :minimize,maximize,close

You will have to log out and log back in for the change to take place. Alternatively you can use the Configuration Editor (gconf-editor) which, if installed, is available under Applications, System Tools.

GNOME3 Shell screenshot

Another method is to use dconf-editor which you may need to load on your system as it is not installed by default. However, be warned, dconf and dconf-editor both seem to be highly unstable as of the date of this post. Worse still, absolutely no documentation or manpages are currently provided for dconf or dconf-editor.

Alternatively, you can customize a small subset of the GNOME Shell using the new Tweak Tool (gnome-tweak-tool.)
GNOME3 Shell screenshot
Astute readers will notice that my version of gnome-tweak-tool is different than the default OOTB tool. That is because I edited /usr/share/gnome-tweak-tool/shell.ui and changed a few property settings such as:

    <property name="title" translatable="yes">GNOME Tweak Tool</property>
    <property name="resizable">True</property>

This utility, like many others, does not show up in the Application Overview. You have to use the Searchbar to access it.

Incidently, Tweak Tool can be used to add minimize and maximize buttons to windows. See the above screenshot. Observe also the different theme and the dark colored titlebars. All will be revealed! Just keep reading.

As stated previously, the default GNOME Shell theme is Adwaita. You can modify this theme by editing /usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml. One of the more interesting sections of this configuration file is:

<frame_geometry name="normal" title_scale="medium" rounded_top_left="4" rounded_top_right="4">
        <distance name="left_width" value="1" />
        <distance name="right_width" value="1" />
        <distance name="bottom_height" value="2" />
        <distance name="left_titlebar_edge" value="0"/>
        <distance name="right_titlebar_edge" value="0"/>
        <distance name="title_vertical_pad" value="13"/>
        <border name="title_border" left="10" right="10" top="1" bottom="1"/>
        <border name="button_border" left="0" right="0" top="1" bottom="3"/>
        <aspect_ratio name="button" value="1"/>

If you are already using the GNOME Shell, you probably have noticed that it is difficult to grab the frame of a window to stretch it. This is because the frame is only 1 pixel wide at the sides and 2 pixels in height on the bottom. To make windows easier to grab, I suggest you change each of these values to 3, 3 and 5 respectively. If you want a less intrusive titlebar, I suggest you change the value of title_vertical_pad to 8.

        <distance name="left_width" value="3" />
        <distance name="right_width" value="3" />
        <distance name="bottom_height" value="5" />     
        <distance name="title_vertical_pad" value="8"/>

The other sections of this file that you may wish to customize are the color constants:

<!-- meaningfull constants -->
<constant name="C_border_focused" value="blend/#000000/gtk:bg[NORMAL]/0.6" />
<constant name="C_border_unfocused" value="blend/#000000/gtk:bg[NORMAL]/0.8" />
<constant name="C_border_attached_focused" value="blend/#000000/gtk:bg[NORMAL]/0.4" />
<constant name="C_titlebar_focused_hilight" value="gtk:base[NORMAL]" />
<constant name="C_titlebar_unfocused" value="blend/gtk:base[NORMAL]/gtk:bg[NORMAL]/0.4" />
<constant name="C_title_focused" value="blend/gtk:fg[NORMAL]/gtk:bg[NORMAL]/0.1" />
<constant name="C_title_focused_hilight" value="gtk:base[NORMAL]" />
<constant name="C_title_unfocused" value="blend/gtk:text[NORMAL]/gtk:bg[NORMAL]/0.9" />

<!-- color of the button icons -->
<constant name="C_icons_focused" value="gtk:text[SELECTED]" />
<constant name="C_icons_focused_pressed" value="#ffffff" />
<constant name="C_icons_unfocused" value="blend/gtk:text[NORMAL]/gtk:bg[NORMAL]/0.9" />
<constant name="C_icons_unfocused_prelight" value="gtk:bg[NORMAL]" />
<constant name="C_icons_unfocused_pressed" value="blend/#000000/gtk:bg[NORMAL]/0.7" />
<constant name="D_icons_unfocused_offset" value="2" /> <!-- offset of the unfocused icons -->
<constant name="D_icons_shrink" value="1" /> <!-- increasing this value makes the icons in buttons smaller -->
<constant name="D_icons_grow" value="0" /> <!-- increasing this value makes the icons in buttons bigger -->

If you make the following changes to metacity-theme-3.xml:

<constant name="C_border_focused" value="#000064" />
<constant name="C_border_unfocused" value="#0052FF" />
<constant name="C_border_attached_focused" value="#000064" />
<constant name="C_titlebar_focused_hilight" value="#000064" />
<constant name="C_titlebar_unfocused" value="#0052FF" />
<draw_ops name="titlebar_fill_focused_alt">
        <gradient type="vertical" x="0" y="0" width="width" height="height">
                <color value="#6B6EAC"/>
                <color value="#000064"/>
<draw_ops name="titlebar_fill_unfocused">
        <gradient type="vertical" x="0" y="0" width="width" height="height">
                <color value="#7096E3"/>
                <color value="#0052FF"/>

and reload the Shell, you will have colored window titlebars and frames:.

GNOME3 Shell screenshot

Notice the icons on the top right hand corner of your screen. These are know as status icons and are displayed by a number of utilities that provide some sort of status including a11y, display, keyboard, volume, bluetooth, network, battery’. The icons are known as SYMBOLIC icons. If you want to display color icons instead of symbolic icons, edit panelMenu.js and change SYMBOLIC to FULLCOLOR on the highlighted line shown below:

SystemStatusButton.prototype = {
    __proto__: Button.prototype,

    _init: function(iconName,tooltipText) {, 0.0);
        this._iconActor = new St.Icon({ icon_name: iconName,
                                        icon_type: St.IconType.SYMBOLIC,
                                        style_class: 'system-status-icon' });;

Currently, there is no built-in mechanism for changing GNOME Shell themes. I understand that this functionality is planned for inclusion in a future version of the GNOME Shell. However, it is quite easy to change the theme if you are careful. As an example, I will walk you though the steps to use the GNOME Shell Dark Glass theme designed by the English digital artist Sean Wilson together with the refFresh 11 wallpaper (background) by the artist Salman Arif.

The number of files in the new theme is surprisingly small:

$ ls
calendar-arrow-left.svg       scroll-button-down.png
calendar-arrow-right.svg      scroll-button-up-hover.png
calendar-today.svg            scroll-button-up.png
close.svg                     section-more-open.svg
close-window.svg              section-more.svg
corner-ripple.png             separator-white.png
dash-placeholder.svg          toggle-off-intl.svg
filter-selected.svg           toggle-off-us.svg
gnome-shell.css               toggle-on-intl.svg
hover-indicator.svg           toggle-on-us.svg
process-working.png           ws-switch-arrow-down.svg
running-indicator.svg         ws-switch-arrow-up.svg

Download the theme and unzip it in a temporary directory. A subdirectory called theme will be created and it will contain the above files. Back up the contents of the current GNOME Shell theme directory /usr/share/gnome-shell/theme. Then copy the contents of the theme subdirectory to /usr/share/gnome-shell/theme.

Download the wallpaper (reFresh_II_by_salmanarif.rar) and unpack it. You may have to install the rar utility! It does not ship with Fedora but is available from RPM Fusion and elsewhere. There are a number of different wallpaper files in the archive:

$ ls *.jpg
1024x640.jpg  1280x1024.jpg  1280x960.jpg  1600x1200.jpg  1920x1080.jpg  2560x1600.jpg  ZuneHD.jpg
1024x768.jpg  1280x720.jpg   1366x768.jpg  1600x900.jpg   1920x1200.jpg  2560x1920.jpg
1152x864.jpg  1280x800.jpg   1440x900.jpg  1680x1050.jpg  1920x1440.jpg  iPhone.jpg

Each image is sized for a particular display geometry. Install the appropriate wallpaper file using the background tool which is available in the GNOME Shell Settings panel.

The new wallpaper is stored in ~/.cache/gnome-control-center/backgrounds:

$ gsettings list-recursively org.gnome.desktop.background
org.gnome.desktop.background color-shading-type 'solid'
org.gnome.desktop.background draw-background true
org.gnome.desktop.background picture-filename '/home/fpm/.cache/gnome-control-center/backgrounds/6ccf207fc0f4eac6b1e5e9c9dbe93c93ffaea4c1059d6cf36219dbe7380e2d19'
org.gnome.desktop.background picture-opacity 100
org.gnome.desktop.background picture-options 'zoom'
org.gnome.desktop.background primary-color '#0a0a19192c2c'
org.gnome.desktop.background secondary-color '#351b74c1c77d'
org.gnome.desktop.background show-desktop-icons false

For details of standard names and colors, see /usr/share/themes/Adwaita/gtk-3.0/gtk.css. You can overwrite such names and colors using your own custom CSS file, i.e. ~/.config/gtk-3.0/gtk.css.

When you restart the GNOME Shell, you should see the following screen:
GNOME3 Shell screenshot

This is what your Applications Overview should look like:
GNOME3 Shell screenshot

Note that the previous customizations to metacity-theme-3.xml are still in place:
GNOME3 Shell screenshot

This is actually a very nice theme and quite easy on the eyes. It has become my default theme for now.
GNOME3 Shell screenshot

I particularly like how the search tool output is themed.
GNOME3 Shell screenshot

By the way, as stated earlier, Alt-F2 r (or Alt-F2 restart) reloads (restarts) the GNOME Shell. If you just want to load a new GNOME Shell theme, it is faster to use Alt-F2 rl. This only calls the JavaScript function that reloads the shell theme.

Turning now to the question of icon customization. To configure the layout of the application icons in the GNOME Shell, you have to modify /usr/share/gnome-shell/theme/gnome-shell.css. Note that the contents of this file may vary as it is dependent on the particular theme that you are using. In the case of the Dark Glass theme, here are the modifications necessary to reduce the size and layout of the displayed icons by 50% in Applications Overview.

.icon-grid {
    spacing: 18px;                       /* was 36px */
    -shell-grid-item-size: 35px;         /* was 70px */

.all-app .icon-grid {
    -shell-grid-item-size: 59px;         /* was 118px */

all-app .overview-icon {
    icon-size: 48px;                     /* was 96px */

Here is what Applications Overview looks like when the GNOME Shell is restarted.
GNOME3 Shell screenshot
By the way, with this theme, running applications are indicated by a light pane around them instead a glow behind the application name. I will leave it as an exercise for you to reduce the size of the displayed application name.

What if I want the GNOME Shell to display a different icon for the GNOME Tweak Tool? There are two places you need to modify. The first is /usr/share/applications/gnome-tweak-tool.desktop:

[Desktop Entry]
Name=Tweak Advanced Settings

I am going to change the Icon key-value pair to preferences-desktop-personal. You can see the available icons if you look in /usr/share/icons. Which icon file is actually selected depends on the current icon theme and the icon lookup mechanism. Icon lookup is first done in the current theme, then recursively in each of the current theme’s parents and finally in the hicolor default theme. As soon as an icon of any size is matched, the search stops. See the Icon Theme specification for further information.

Icon information is also stored in a property named icon_name in /usr/share/gnome-tweak-tool/shell.ui. This also needs to be changed to preferences-desktop-personal. When you have modified these two files, you need to run

# desktop-file-validate /usr/share/applications/gnome-tweak-tool.desktop

Incidently if you change:




in /usr/share/applications/gnome-tweak-tool.desktop, the GNOME Tweak Tool will be displayed in the Application Overview. By design, applications marked Settings are not displayed in the Application Overview.

You can also add your own icon for an application to one of the icon themes under /usr/share/icons. If you do this, you need to update the icon cache using gtk-update-icon-cache before the icon is available for use. Here is a simple shell script which updates all the icon caches for you.


find /usr/share/icons -maxdepth 1 -type d | \
while read -r THEME; do
   if [[ -f "$THEME/index.theme" ]]; then
      echo "Updating $THEME cache"
      gtk-update-icon-cache -f -q "$THEME"

Suppose you want to remove the Available and Busy menu options from the user menu (the menu under your name.) Just edit /usr/share/gnome-shell/js/ui/statusMenu.js and comment out the following lines in _createSubMenu:

        item = new PopupMenu.PopupImageMenuItem(_("Available"), 'user-available');
        item.connect('activate', Lang.bind(this, this._setPresenceStatus, GnomeSession.PresenceStatus.AVAILABLE));;
        this._presenceItems[GnomeSession.PresenceStatus.AVAILABLE] = item;

        item = new PopupMenu.PopupImageMenuItem(_("Busy"), 'user-busy');
        item.connect('activate', Lang.bind(this, this._setPresenceStatus, GnomeSession.PresenceStatus.BUSY));;
        this._presenceItems[GnomeSession.PresenceStatus.BUSY] = item;

        item = new PopupMenu.PopupSeparatorMenuItem();;

and reload your GNOME Shell.

Turning to the issue of customizing fonts. The default font for GNOME 3 is Cantarell, a new contemporary sans serif open font specially commissioned by GNOME. The current version of Cantarell does not cover all the supported languages in GNOME. This means that, depending on your particular locale settings, you may fallback to another font.
You can use Fontik to tweak and configure some font properties. Other ways of tweating fonts include dconf-editor and gsettings. The GNOME Tweak Tool also enables you to easily change some font settings.

$ gsettings get org.gnome.desktop.interface font-name
'Cantarell 11'
$ gsettings set org.gnome.desktop.interface font-name "Canterell 12"
$ gsettings set org.gnome.desktop.interface monospace-font-name "Monospace 12"
$ gsettings set org.gnome.desktop.interface document-font-name  "Sans 12"
$ settings set org.gnome.desktop.interface text-scaling-factor  "1.1"

Finally, you can no longer customize the screensaver in GNOME 3. When your screen is locked all you get is a black screen with the clock, a lock symbol and your name at the top of the screen. There are plans to remove gnome-screensaver in GNOME 3.2 and putting its functionality partially in the GNOME Shell and the remainder in gnome-session or gnome-settings-daemon. It may then be possible to write a themed Clutter-based screensaver extension for GNOME Shell.

You probably have noticed that the GNOME Shell supports window tiling. By this, I mean that you can tile a window by dragging it to either the left or right edges of the screen. Typically nearly half the window must go over the edge before a light blue rectangle outlining the tile appears. If you release the window at that time, the window will be automatically tiled to match the outline. If you dislike this feature, you can turn it off using gconf-editor. Set desktop->gnome->shell->windows->edge_tiling to FALSE.

Well, it is time to wrap up this post. Obviously there is a lot more to the subject of customizing the new GNOME Shell but I have tried to cover the basics. Unfortunately, at present, there is a dearth of good accurate information on the underpinnings of the GNOME Shell out there on the Internet so I cannot point you to any reference material on the subject. Hopefully the GNOME developers will provide complete documentation in the future.

P.S. If you have found this post via an Internet search, you might be interested to know that I have written a number of other posts in this blog about configuring and extending the GNOME 3 Shell. Also you can download all my GNOME Shell extensions from the GNOME Shell Extensions area of my website.

95 comments to Customizing the GNOME Shell

  • jonEbird » Customize Gnome Terminal in Gnome 3

    […] easier solution than I expected. When I decided to figure this out tonight I started by finding a nice tutorial for updating gnome configurations and I thought I was going to end up recommending the following command: gsettings set […]

  • rulet

    How to change the color of selection of a text, desktop icons e.t.?

  • Rouzy

    What is the point to introduce innovations that are user-friendly, while for a slight adjustment to the font or size of the icons, you can edit config files?

  • Philou

    They are a little error, you write “buttom” and not “button” here :
    gconftool-2 –set /desktop/gnome/shell/windows/buttom_layout –type string :minimize,maximize,close
    and not
    gconftool-2 –set /desktop/gnome/shell/windows/button_layout –type string :minimize,maximize,close

    Thanks for this post, very usefull !!!

  • Martin

    If possible, can you post your whole extension config files. shell.ui and others. THanks

  • Pascal

    Thanks you for the great post!

    Can you give me a hint (preferably a solution ;-)) how to set things so that a window is focused AND raised when the mouse cursor enters it (without actually clicking into the window)? Is that possible at all? Best would be to be able to set a certain delay for the window activation/raise.

    And another tricky problem: How can I assign two special mouse buttons (or certain keys on the keyboard) to toggle up or down in the workspace list? At the time being one has to go to Activities and then back to the dynamic workspace selector, and the whole thing fails when I run a virtual machine in full screen mode in a workspace.

    Anyway, your post is a very helpful introduction into the internals of GNOME shell.

  • I start to use the Gnome 3.2 in Ubuntu 11.10 today and i’m wondering if (and how) it’s possible to remove the application icon from the main bar.

    Example: When Google Chrome is open, in the right side of the “Activities” is the “Google Chrome” written on the Google Chrome Icon. Is possible to remove this icon and let only the Text? Seriously, this will make it a lot beauty.


  • I am using Ubuntu 11.04 but i dont know how to configure its Gnome shell and even I never know that it is configurable.This post guides me well and solve my problem.Well i think that u r doing it on fedora I have also used fedora but I think it works with Ubuntu as well.

  • Amol

    Is there any way to change the default search provider in gnome-shell ?

    • Tim

      I did this:

      sudo geany /usr/share/gnome-shell/search_providers/google.xml

      (but you can get gedit not geany ;) )
      and this file I changed the name to DuckDG (what ever you want)
      I don’t touch the image tag but the URL
      If you want another then you need to chenage the seach template line (URL)
      here is the whole file:
      —————————Start of File:

      DuchDuckGo Search

      ——————————End of File

  • venorika

    Hello and thanck you very much for all. J manager to delete the accessibility icon, the available and busy message but now i would like – j know it’s a detail – the bubble near my name. Is it possible ?
    Thanks for your answer

  • dros

    Hi Folks,

    dunno if I´m right here. But I googled my fingers down to the bone. How can I export my nautilus gnome3 places and keyring saved passwords.

    In other words where are gnome3 places stored ?
    And where are gnome3 keyring passwords stored ?

    thanks for your help in advance

  • mike

    Awesome post, specifically the part about changing icons. However, even when the icon is changed in the activities menu, the old icon remains in the panel next to the name of the window. Is there a way to fix this? Thanks

  • Thank you for making this page I learned a lot from this.

  • Sarah

    Just what I’ve been looking for! Thanks! It helped me solve my problem. :)

  • ari jeremy

    Great article !


    I tried to increase the font size on the app grid screen but in vain. Can anyone please point me to the right place in /usr/share/gnome-shell/theme/gnome-shell.cssreat article

  • pacifico

    Thanks for this great tutorial, started using Fedora 16 with gnome3 on my Thinkpad T500,

    And was wondering what could I change, and came around your post.

    very useful, I was reading people complaining about the minimize buttons and icons sizes, jeje

    Thanks again

  • Marcelina J. Smith

    Very useful info. Nicely done. Thanks.

  • Abraham Jose

    Help please! I tried to install gnome-shell-extensions(experimental debian) in Debian Sid OS. the alternative-status-menu made gnome-shell crash everytime I login. So, I purged it and afterwards, ALT+F2 and “r” or “ch” “lg” etc internal commands are not working! I have even reinstalled all gnome-shell related packages. it didnt helped.

    thank you

  • Robert

    Great tutorial & well explained applications. Glad to be on this site, now I know how GNOME Shell is customized. I bookmarked this page for reference. Thank you for sharing.

  • Okay looks complicated but I’m gonna use this as a reference and studying it. thanks for posting..

    • Do not forget that this post is about GNOME Shell 3.0. As of now, the current version of GNOME Shell is 3.2. I have a separate post covering GNOME Shell 3.2 extension changes.

  • Wow this is amazing. I just bought a GNOME shell and I am custumizing it right now! :D

  • Alfonso

    Thank you very much, for all your posts, they are very useful and informative.
    If you allow me, I want to add my two cents: I had the same “problem” that Philou had… pasted your code and nothing happened even after logout/login.
    Listing the properties with “gconftool-2 –all-entries /desktop/gnome/shell/windows” two items will be shown:
    buttom_layout = :minimize,maximize,close
    button_layout = :close
    i.e. the right one, and the one with the typo.

    So if you write any string it will be added to the properties despite of the fact it is a real property or not (I hadn’t imagine it).