Documenting GNOME Shell Extensions is an ongoing process and some information here may be outdated, incomplete or otherwise inaccurate. Please be patient while we continue to improve it and see the Getting Help section if you have questions that are not answered here.
The extension system is a replacement for the "applets" or "widgets" system of GNOME 2. Extensions can add their own items to the top panel, but they can also do much more: adding a custom search provider, for instance. For more information, see this post.
There is a large collection of reviewed extensions at the official GNOME Shell Extensions website and this is where most users will install extensions from. Extensions can be installed/uninstalled, enabled/disabled and the preferences launched from the website. This is made possible by a browser WebExtension that communicates with a small desktop process. There is also a plugin available for GNOME Software that allows you to browse and install extensions directly from the desktop.
Please consult the documentation for your distribution if these were not already installed with GNOME.
Some extensions may provide a preferences dialog for configuration options or settings. These can be accessed a number of ways:
The Installed tab of the GNOME Extensions website
The Extensions tab of GNOME Tweaks
The gnome-shell-extension-prefs tool shipped with GNOME Shell
Each of these tools can be used to enable, disabled and launch the preferences window of extensions. More advanced configuration may be available at the dconf path /org/gnome/shell/, while many extensions store configuration options under the /org/gnome/shell/extensions/ path.
Installed extensions are also listed in the Looking Glass developer console.
Here we have a growing number of tutorials and guides for creating extensions, as well as working with some of the developer tools included with GNOME Shell.
- At the time of writing, this is most up to date and thorough tutorial on writing Shell extensions. For educational purposes it avoids the use of many higher-level tools available to extension authors.
- Most extension authors will never have to worry about GObject referencing or memory leaks, especially if writing clean, uncomplicated code. This page describes some common ways extensions fail to take scope into account or cleanup main loop sources and signal connections.
As of GNOME Shell 3.34, there is a new gnome-extensions command-line tool for working with extensions:
$ gnome-extensions Usage: gnome-extensions COMMAND [ARGS…] Commands: help Print help version Print version enable Enable extension disable Disable extension reset Reset extension uninstall Uninstall extension list List extensions info Show extension info show Show extension info prefs Open extension preferences create Create extension pack Package extension install Install extension bundle Use “gnome-extensions help COMMAND” to get detailed help.
These are some older pages, which are likely out of date, but may still contain useful information. These will ultimately either be reviewed and updated, or archived:
- Finnbarr's guides
On systemd-based systems (like Debian), you can see error and log output of extensions using journalctl /usr/bin/gnome-shell -f. On other systems, logs might be written to ~/.xsession-errors.
You can log messages from an extension into this log for informational or debugging purposes using log(msg).