GNOME Shell Theme Selector Preview

The GNOME Shell developers appear to have no interest at present in supporting custom theming of the GNOME Shell. Frankly I do not blame the developers for taking this position as they had more than enough work on their hands getting the first release of the GNOME Shell stabilized and out the door and have lots of work to do to complete the next major version of the GNOME Shell for GNOME 3.2. I would have done the same.

According to Owen Taylor, maintainer of the GNOME Shell:

From the perspective of the GNOME Shell team, GNOME Shell themes are both not interesting and not supportable … we cannot commit to any stability of the CSS class names or actor hierarchy.

However that has not stopped pathfinders from developing custom themes for the GNOME Shell and tools for installing and using these custom themes.

A theme is a general term for all of the artwork & the color schemes used when rendering everything you see in a GNOME desktop. Themes are mostly static collections of image files that are used to construct window frames and widgets. A theme engine is a code module that uses a theme to style the look of the widgets that are drawn in your desktop. Two different theme engines could use the same theme files but render different visual results. Engines are more complex to create but can render better visual effects.

Current public support for Shell theming is limited to the user-theme extension in the GNOME Shell extensions repository which was set up by Giovanni Campagna some months ago and the GNOME Tweak Tool by John Stowers. While both of these solutions enable custom theme support, neither of these solutions is satisfactory as far as I personally am concerned. The user-theme extension requires a user to use either gsettings or gconf to specify a specific theme and does not provide a visual preview of of the theme. While the gnome-tweak-tool is an excellent tool in many respects and has a long life ahead of it, it is problematic as far as theming is concerned, does not provide a theme preview and requires you to manually reload the GNOME Shell to see the new theme.

I decided that I would explore embedding theme selection functionality directly into the GNOME Shell as another option in the Activities screen. A preview and some information is provided about each of the available themes. Clicking on a theme selects and activates the theme there and then. You can quickly cycle through the supported themes, select a theme and see the resultant presentation styling changes immediately..

Here are a couple of screenshots of the themeselector extension in action using five of Half-Left‘s excellent GNOME Shell themes together with the default Adwaita theme:
GNOME3 Shell screenshot

GNOME3 Shell screenshot

GNOME3 Shell screenshot

GNOME3 Shell screenshot

There is a slight problem with the Dark Glass theme. The titles are actually displayed but they are displayed in black on a black background.

GNOME3 Shell screenshot

GNOME3 Shell screenshot

This all works because each theme is located in its own subdirectory under a themes directory and contains all the files and data necessary for that theme:

$ ls -l themes
total 28
drwxrwxr-x. 2 fpm fpm 4096 Apr 25 12:47 Adwaita
drwxr-xr-x. 2 fpm fpm 4096 Apr 25 12:48 ANewHope
drwx------. 2 fpm fpm 4096 Apr 25 12:48 Atolm
drwxrwxr-x. 2 fpm fpm 4096 Apr 25 12:47 DarkGlass
drwxrwxr-x. 2 fpm fpm 4096 Apr 25 12:48 DeviantArt
drwxrwxr-x. 2 fpm fpm 4096 Apr 25 12:48 Elementary
drwxrwxr-x. 2 fpm fpm 4096 Apr 25 12:48 SmoothInsert

$ cd themes/Atolm
$ ls -l
total 396
-rw-r--r--. 1 fpm fpm   3413 Apr 13 15:04 calendar-arrow-left.svg
-rw-r--r--. 1 fpm fpm   3414 Apr 13 15:04 calendar-arrow-right.svg
-rw-r--r--. 1 fpm fpm   4413 Apr 11 20:59 close.svg
-rw-r--r--. 1 fpm fpm   4337 Apr 11 21:01 close-window.svg
-rw-r--r--. 1 fpm fpm   1315 Mar 22 03:55 corner-ripple.png
-rw-r--r--. 1 fpm fpm   3013 Mar 22 03:55 dash-placeholder.svg
-rw-r--r--. 1 fpm fpm   3401 Apr 11 21:15 filter-selected.svg
-rw-rw-r--. 1 fpm fpm    245 Apr 25 12:48 metadata.json
-rw-rw-r--. 1 fpm fpm 231713 Apr 22 23:57 preview-atolm.png
-rw-r--r--. 1 fpm fpm   4097 Mar 22 03:55 process-working.png
-rw-r--r--. 1 fpm fpm  10056 Mar 22 19:30 process-working.svg
-rw-r--r--. 1 fpm fpm  36293 Apr 13 15:03 stylesheet.css
-rw-r--r--. 1 fpm fpm  15545 Apr  9 19:21 toggle-off-intl.svg
-rw-r--r--. 1 fpm fpm  14295 Apr  9 19:16 toggle-off-us.svg
-rw-r--r--. 1 fpm fpm  13564 Apr  9 19:22 toggle-on-intl.svg
-rw-r--r--. 1 fpm fpm  15358 Apr  9 19:19 toggle-on-us.svg
-rw-r--r--. 1 fpm fpm   3409 Apr 11 18:23 ws-switch-arrow-down.svg
-rw-r--r--. 1 fpm fpm   3252 Apr 11 18:22 ws-switch-arrow-up.svg

$ cat metadata.json
   "name": "Atolm", 
   "author": "Half-Left", 
   "version": "1.0",
   "type":   "custom",
   "thumbnail": "preview-atolm.png", 
   "stylesheet": "stylesheet.css",
   "url": "" 

Other optional supported tags include disabled which when set to boolean FALSE indicates that a theme should not be displayed by this extension, and shell-version and gjs-version which can be used to restrict a theme to a particular GNOME Shell or GJS (GNOME JavaScript) version. You probably will never need to use either shell-version or gjs-version but I felt that it was better to build in this support just in case.

All necessary metadata about the theme is stored in each theme’s metadata.json. Note that this enables the theme preview image and theme stylesheet to be named anything you like. The themeselector extension reads each theme’s metadata.json file and can figure where to find the theme preview image and stylesheet.

By the way, the XDG Base Directory specification is silent on the issue of where theme data should reside. Both the user-theme extension and gnome-tweak-tool expect theme files to reside under $HOME/.themes/’THEMENAME/gnome-shell/ and expect the theme stylesheet to be named gnome-shell.css. I disagree with that location and think that GNOME Shell theme files should live under $XDG_DATA_HOME, for example, $HOME/.local/share/gnome-shell/themes, just as GNOME Shell extensions live under $HOME/.local/share/gnome-shell/extensions. Let the flame wars start. I will put on my asbestos suit!

You can download this version of the themeselector extension here. It contains all five Half-Left themes shown above. Place the downloaded tarball in $HOME/.local/share/gnome-shell/ and unpack it. A new directory will be created under $HOME/.local/share/gnome-shell/extensions to contain the extension code. A new directory called themes will be created under $HOME/.local/share/gnome-shell/, and under this directory a series of directories will be created, one per theme.

You need to install the following schema for in a file called /usr/share/glib-2.0/schemas/

<schemalist gettext-domain="gnome-shell-extensions">
  <schema id="" path="/org/gnome/shell/extensions/user-theme/">
    <key name="name" type="s">
      <summary>Theme name</summary>
      <description>Name of the custom theme</description>

If the user-theme extension is installed, this file will already be present in /usr/share/glib-2.0/schemas. If you manually install it, you must to compile the new schema using glib-compile-schemas. See the glib-compile-schemas man page for further information if you are unfamiliar with this utility.

After restarting your GNOME Shell, you should see the Themes option in the Activities overview screen. This is still beta software – so make sure you first back up $HOME/.local/share/gnome-shell/ if you have anything important that you need to preserve. Currently global custom themes are not supported, only per-user custom themes. I plan to support global custom themes in a future release in the next week or two.

Enjoy! Please let me know about any problems you encounter.

[28 APRIL 2011] NOTE: The location of theme files and names of files as shown in this post will almost certainly change in the final version of the themeselector extension. I am working to get consensus among interested parties on a specification for GNOME Shell theme packaging and theme selectors. Once this is achieved I will update the extension and this post.

[30 APRIL 2011] NOTE: A new version (v0.9) of the themeselector extension is available here. Please use this version instead of Unpack in a temporary directory. Please read the README file for installation instructions. Do not follow the above instructions. Note that the location of the themes and the theme metadata file has changed in this version.

[1 NOVEMBER 2011] NOTE: This version of the themeselector extension only works with version 3.0 or version 3.1 of the GNOME Shell.

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.

51 comments to GNOME Shell Theme Selector Preview

  • If gnome-tweak-tool requires the shell to be restarted then that is a bug (as it works for me / used to work for me). Can you please file a bug and attach a theme so I can fix it.

    • You have a dependency on another extension being enabled and working. I do not use the user-theme extension but have the extension schema installed. You could just as easily reload the shell from within gnome-tweak-tool. Works fine for me.


      def _shell_reload_theme(self):
      #reloading the theme works OK, however there are some problems with reloading images.
      #however, smashing the whole shell just to change themes is pretty extreme. So we
      #just let the user-theme extension pick up the change by itself
      # “The shell must be restarted to apply the theme”,
      # “Restart”,
      # lambda: self._shell.restart())

  • Charles Bowman

    I’ve been looking for something like this, unfortunately it crashes my desktop after logon.

    Extracting the tarball doesn’t automagically create the directories as explained in your instructions, however I relocated them as described.

    Added the snippet of source to the bottom of the /usr/share/glib-2.0/schemas/

    Also did the glib-compile-schemas process for good measure.

    I repeated the process twice & got the same crash both times. I used the recovery console to delete the extension and was able to return to the desktop.

    Whenever I have attempted to install gnome-tweak-tools (this is my 4th or 5th try with gnome 3 on ubuntu) it always shows “User theme extension not installed” (something similar). In addition, since installing this extension gnome-tweak-tools will not load any more.

    I appreciate what you are trying to do here and hope that whatever information I provide can be of some use to you.

    • I am worried about the fact that you modified /usr/share/glib-2.0/schemas/ to add something. If this file already existed, you should not have had to touch it.

      I suggest you revert back to the original version of this file, re-enable the user-theme extension (because gnome-tweak-tool has a dependency on it) and test gnome-tweak-tool again.

      Another way would be to blow away this file and the user-theme extension directory and reinstall the user-theme-extension and then test gnome-tweak-tool again.

      Please let me know how you get on.

  • Charles Bowman

    Ok, restored the schema file to original condition, gnome-tweak-tool is functioning again.

    However, I still have the “User theme extension not enable” message. This has been a recurring problem and is probably the root problem. I am able to change themes & icons with gnome-tweak-tool despite that message. Additionally whenever I have tried to download the git and make the gnome-shell-extensions it always gives me recursive errors. I end up copying the extensions to the .local/share/gnome-shell/extensions directory manually and they all appear to work.

    The Fedora & Arch users seem to be further along with Gnome 3 than the Ubuntu users at this point. Could it simply be an Ubuntu problem? I haven’t found any good resources for marrying Ubuntu & Gnome 3 since everyone else seems so taken with Unity at this point.

  • Charles Bowman

    It would appear that when trying to ./ the gnome-shell-extension gnome-desktop-3.0 is not found.

    When I look in my package manager it doesn’t exist. The closest thing I have is gnome-desktop3-data.

    Obviously I will need a way to overcome that problem to cleanly install the shell extensions before I can properly use your extension, which I am anxious to do.

    I apologize for wasting your time trying to debug what is obviously a fault in ubuntu.

  • Charles Bowman

    I’m damn near ecstatic, thanks to Gayan over on I was able to successfully install the gnome-shell-extensions using this:

    git clone
    cd gnome-shell-extensions
    ./ –prefix=/usr
    make && sudo make install

    After that it was a simple matter of copying your extension directory to the proper location & restart the system.

    Your theme selector works great!

    Many thanks.

  • Charles Bowman

    Correct, there appear to be some slight differences installing the gnome-shell-extensions in Ubuntu compared to Fedora.

    I consider it a “bug” in Ubuntu but it’s probably more ignorance on my part.

    I noticed over on Deviant Art that you will probably get this integrated with gnome-tweak-tools, I want to commend you all for applying your talents to help the community. It’s people like you that make learning & using linux such a pleasure.

  • Rahul Sundaram

    I maintain the GNOME Shell Extensions package in Fedora along with a couple of others and this one works well for me. Was wondering if you were planning on submitting it upstream? I would like to enable this extension for Fedora and if this remains a separate source, it has to go through a separate package review which is tedious

    • I am happy to provide the extension to the Fedora community (and anybody else) but would like to maintain it as a separate RPM (at least for now) for a number of reasons.

      One – it is much bigger than the existing extensions in gnome-shell-extensions by a factor of 5 or more because of theme information. Two – it clashes with the existing user-theme extension (which should be modified or removed because it does not play fairly with other extensions that play with themes and forces tools like gnome-tweak-tool to have a dependency on it.

      Currently there is no agreement on shell theme packaging or how shell theme selectors should interact with shell theme packages. I am working with a number of extension and theme developers to try and agree such a specification. This will eliminate such issues in the near future.

  • @fpmurphy,

    the user-theme extension might be icky, and it might be rude for gnome-tweak-tool to depend on it, but IMHO the real fix is to move the user-theme extension into gnome-shell proper, thus fixing all problems. Then theme selectors like yours, and g-t-t could just change the gsettings key at will, and the shell will pick up the change.

    Actually, even just moving the schema into gnome-shell would be sufficient. I suggest you file a bug, then we can discuss it with upstream there.


  • Brian Millett

    You mention that the xml file is

    do you mean

    as that is what is installed from gnome-shell-extensions-user-theme-3.0.1-1.f016b9git.fc15.noarch

  • okaboy

    Thanks for your good work ;)

    The code of schema file has an error:

    it would be

  • Dean Loros

    I can confirm that this also works in LMDE with experimental debian sources..I had to do exactly the same thing that Charles Bowman did with his Ubuntu install. Works very well–no surprises.

    I commend you on a job very well done!!!!

    I’m including the link to this page in my Gnome-Shell thread:

  • Dean Loros

    Greetings again!!!!

    A “feature” request if I may…….I have 10 themes installed now & the selection window will not scroll to “see” the 10th theme..looks like it will only allow 9 themes to be visible. Another thought would be to allow the previews to resize smaller if there are more than 9 themes…..

    What do you think?


  • Dean Loros

    Greets again…

    I “mucked” about with your extension…changed the number of Columns to 6, grid spacing to 5, grid padding to 15 & resized the thumbnails to 64×48. I now have space for 24 themes….all still look good enough to see the differences for a preview…

    I do hope that this won’t be enough space very soon……


  • Dean Loros

    Last for the evening—reverted the grid spacing & padding–reduced the columns to 5–left the thumbnail sizing the same…enough for 20 themes.

  • Darko82

    Sorry for my terrible english.
    I have a little problem.
    I’m on arch i686 and when I install your extension and change the theme, my dock extension has no background, even if I return to Adwaita theme.
    If I remove your extension everything goes normal.
    Nobody else?

  • zorro

    thanks for the work, after installing gnome-shell-extensions-git, alt + tab keys do not work anymore.
    solution exists

  • I’ve read and applied a large portion of what you posted in this, and the older articles.

    Thanks again, my Gnome 3.0 experience on Ubuntu has benefited greatly from your information & extensions. I’m sharing what I’m learning and actually created a custom default Ubuntu gnome 3.0 remaster which I’m sharing with as many people as possible. (gNatty Gnome)

  • Colin

    I tried installing this on Ubuntu 11.04 with Gnome 3 installed from the ppa. When I restarted my gnome session, the desktop immediately crashed, and forced me to logout. I removed the theme selector files in recovery mode, and the desktop booted again. Any idea how I can fix this? I was using the latest version (0.9).

  • Breakz

    Is there any way to remove the panel on the right of the desktop?or how can i manually remove the shell extensions?
    i deleted the folder with the files but the panel is still there.


  • Colin, do you have the gnome-shell-extension-user-theme installed?

    If you click on my name you will be transported to a thread on ubuntu forums where you might get a little assistance oriented to your distro.

    While the extensions are distro agnostic ubuntu seems to need a little extra TLC at this early stage of integrating Gnome 3.0

  • The download 404’s. :( I really wanted to install this extension.

  • BigE

    Is there a way to scroll through the themes? I have more than what is displayed on the screen and it doesn’t seem to allow me to scroll down at all.

  • […] here.  Then, that blog also has an eye catching way to change the Gnome theme, which is documented here.  I thank the authors of all of these posts, which helped install and improve my Gnome Shell.  I […]

  • Vladimir

    I have available, only 3 out of 5 themes, what to do?
    У меня доступно только 3 темы из 5, что делать?

  • I’m on F15. I tried theme selector from repo, it doesn’t work. However, I did try yours, it work pretty well. Thanks!

    Any chance for you to modified the ‘dock’ to have auto-hide features? If not, I might stick with awn for now :)

  • Kavin

    I have 8 themes but gnome-shell-extension-user-theme showing only six themes, How can i fix this?

    • I need to add scrolling to the themeselector window to support this.

      I plan to replace a new version of themeselector in the next few weeks.

      Keep an eye on http://

  • Xylocaine

    i’m on F15 i use theme selector from here version 0.9, it is very useful tool thanks for taking the time write such tool,

    if you are open to suggestion then :

    – themes vertically exceeds to the panel area if you have more than 6 theme.

    – add a scrollbar to the list something similar to the “Apllication selector”.

    problems :

    – only one problem when i choose a different theme other than Adwaita then restart the pc it return back to Adwaita and after i click the activities then quite it return back to the selected theme,


    • Sounds like you have the user-theme extension installed.

      If you have it installed, go to /usr/share/gnome-shell/extensions and delete the user-theme@… subdirectory.
      Do not uninstall it using yum. You need the gsettings key/gschema component of the user-theme package.

      Thanks for the suggestions. I will try and incorporate them in the next version of themeselector which I plan
      to start work on shortly.

  • Xylocaine

    user-theme extension deleted not using yum, it seems it did the trick it’s working like a charm thanks now.

    well cannot wait to get it till then hope you have a good days.

    definitely will keep my eye on your blog.


  • allienz123

    Is there a way to change the preview size in theme selector cause i’m not be able to select another themes when it reached more than 9 themes ????

  • For Ubuntu 11.04

    how to use gnome-shell without any problem with extensions ?!!

    sudo add-apt-repository ppa:gnome3-team/gnome3 && sudo apt-get update && sudo apt-get dist-upgrade
    sudo apt-get install gnome-shell gnome-tweak-tool

    sudo apt-get purge unity scrollbar* gnome-accessibility-themes
    sudo apt-get install gnome-themes-standard

    Then logout and back in using the GNOME classic (No effects) Session.(no need if you installed your 3d driver just use GNOME Session)
    go to additional drivers install recommended driver restart your sys choose GNOME Session then login

    sudo add-apt-repository ppa:ricotz/testing && sudo apt-get update && sudo apt-get dist-upgrade
    sudo apt-get install gnome-common gnome-shell-extensions-user-theme

    now you’r ready:

    1. go to then download themeselector-0.9.tar.gz and extract it
    2. creat new dir call it then move extension.js and metadata.json in it
    3. move dir to $HOME/.local/share/gnome-shell/extensions/
    4. move the themes dirs to $HOME/.themes/
    5. hit alt+F2 ,r

    Now .. Theme selector work without any problem and shell extensions will work aether in gnome-tweak-tool

    I hope that will help you ,,

    Note: fpmurphy thanks for your extensions it’s great thanks 2 much

  • True that the developers have much work they need to be doing and it is great the others like you pick up the slack.

  • This is the best thing ever invented! Gnome3 + This tool is awesome! :D

  • Da Lucy

    Does not work under Natty/Gnome Shell Missing init function

  • Otaj

    the link for extension reports 404. By the way, Aare you planning to port it to GS 3.2?

  • Richard Macwan

    Please change your download link to in your note on 30th April. The link is broken.