Making GNOME Shell Extensions

Estimated read time: 3 min

Originally published on February 9th, 2013 (Last updated on July 17th, 2020)

I like the GNOME Shell and I’ve liked it since it was in the testing”-repo of Arch­Lin­ux. It’s a fast and aes­thet­ic desk­top envi­ron­ment. But it’s a long way from offer­ing every­thing you’d like to have. Luck­i­ly, it can be extended.

The fol­low­ing advices, instruc­tions or sources where com­piled when GNOME Shell 3.6.2 was the lat­est ver­sion. While spe­cif­ic infor­ma­tion here might be out­dat­ed, the gen­er­al idea still holds val­ue today.

Note that this is not a real step-by-step guide on how to cre­ate your first exten­sion. There are many of those out there and I would just repeat them. Instead, this is more like an advice-col­lec­tion on dif­fer­ent aspects of cre­at­ing exten­sions. So, be sure to check the links.

Basics #

Get­ting into the devel­op­ment of GNOME Shell Exten­sions is a lit­tle hard. The doc­u­men­ta­tion is most­ly not avail­able or outdated.

Here are some sources which helped me to get start­ed (and through development):

Be sure to defi­ant­ly check out the bold links in the list.

Get­ting stuff done #

Above all, if you’re seri­ous about cre­at­ing your exten­sion: Learn to read the source, Luke.

When try­ing to get actu­al work done on your exten­sion, try con­sult­ing the docs (if exist­ing) or search the exten­sion repos for exten­sions which do sim­i­lar things to what you want to do, and look at their sources. Most of them are host­ed on GitHub or Bit­buck­et, but you can also install them and find the sources under ~/.local/share/gnome-shell/extensions/<extension-UUID>/.

When search­ing for a spe­cif­ic func­tion, or more doc­u­men­ta­tion on a par­tic­u­lar func­tion, you can also con­sult man­u­als for bind­ings in dif­fer­ent lan­guages (thought the para­me­ters and return-val­ues might not match exactly).

Mak­ing user interfaces #

To get a native look-and-feel with the Shell, exten­sions can use St (= Shell Toolk­it) to cre­ate UIs for every­thing that inte­grates with the Shell itself, and Gtk for the extension-preferences.

Some Doc­u­men­ta­tion is now avail­able over at the Gnome Docs. It is how­ev­er just a ref­er­ence, which makes it hard to dis­cov­er func­tion­al­i­ty. For some guid­ance, check out this (old­er) expla­na­tion of the St com­po­nents. Read­ing a lot of source-code is still required. See the GNOME Shell Sources.

Doc­u­men­ta­tion on Gtk’s JavaScript bind­ing (which you’ll use for the exten­sion-pref­er­ences) can be found in the in-offi­cial library docs.

Debug­ging #

Look­ing­Glass is not par­tic­u­lar­ly help­ful. It only shows one line of an excep­tion (the descrip­tion) and only if they occur at start­up time (when your exten­sion is first started).

Instead, for full Stack­Traces and run­time-excep­tions, con­sult the ses­sion-log­file. It might be very long and bloat­ed, so I use this handy script to read it:

# Grabs the last session-errors from the current X11 session.
# This includes full Stack-Trace of gnome-shell-extension errors.
# See
tail -n100 ~/.cache/gdm/session.log | less

Should your exten­sion crash the whole Shell, the session.log-file will not con­tain infor­ma­tion on it, because when the shell restarts, a new log-file is cre­at­ed. Go get infor­ma­tion on what crashed the shell, check the ~/.cache/gdm/session.log.old-file.

For debug­ging the prefs-part of your exten­sion, you can launch the pref­er­ences by using the gnome-shell-extension-prefs-tool from a ter­mi­nal. Any excep­tions will be out­put to the con­sole. Addi­tion­al­ly, you can also call the tool like gnome-shell-extension-prefs [uuid] to direct­ly show your exten­sions preferences.

Since there is cur­rent­ly no real way of debug­ging with break­points (there is, but it’s tricky), you can log to the con­sole, using the print()-func­tion. You will see the out­put as men­tioned above (either in the ses­sion-log­file or on the ter­mi­nal when start­ing gnome-shell-extension-prefs-tool).

The future #

At the GNOME Devel­op­er Expe­ri­ence Hack­fest” in Febru­rary 2013, JavaScript was cho­sen to be the offi­cial­ly sup­port­ed lan­guage” for cre­at­ing appli­ca­tions for GNOME:


Prac­ti­cal­ly any high-lev­el, garbage-col­lect­ed lan­guage is much bet­ter than plain C, in terms of pro­duc­tiv­i­ty, once you get used to the idio­syn­crasies of the bind­ings to the Gnome libraries.

So, I’m very hap­py that we have a high-lev­el lan­guage [JavaScript] accept­ed as offi­cial­ly sup­port­ed for Gnome. I was kind of sur­prised that Python, our de-fac­to and his­tor­i­cal­ly best sup­port­ed bind­ing” was­n’t cho­sen, but if this means that anoth­er high-lev­el lan­guage can get as much work put into it, then all the better.


So, there is hope that the API doc­u­men­ta­tion will improve very soon.

Con­clu­sion #

  • Above all: Read the sources!
  • Check out oth­er exten­sion’s sources and learn from them.
  • Don’t get frus­trat­ed by the doc­u­men­ta­tion. Read sources instead.
  • You can ask spe­cif­ic ques­tions on Stack­Over­flow [gnome-shell-exten­sions]

Although it might be a lit­tle hard to get into it, the exten­sion frame­work is quite pow­er­ful. Have fun!

Posted by Lukas Knuth


No com­ment sec­tion here 😄

You can reach me over at @knuth_dev or send me an Email.