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.
Contents
Extensions
The GNOME Shell extension design is designed to give a high degree of power to the parts of the GNOME interface managed by the shell, such as window management and application launching. It simply loads arbitrary JavaScript and CSS. This gives developers a way to make many kinds of changes and share those changes with others, without having to patch the original source code and recompile it, and somehow distribute the patched code.
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.
Getting Extensions
Extensions can be installed from the official GNOME Extensions website, with the help of a WebExtension compatible with Mozilla Firefox and Google Chrome (Chromium) web browsers. See the documentation for your distribution if this was not already installed with GNOME.
Many distributions also have popular GNOME Shell extensions available in their package repositories.
Configuring Extensions
Some extensions may provide a preferences dialog for configuration options or settings. These can be accessed a number of ways:
The Installed page on the GNOME Extensions website
The Extensions App
The gnome-extensions CLI tool included with GNOME Shell
Each of these tools can be used to enable, disable and launch the preferences window of extensions.
Creating Extensions
As GNOME Shell and extensions are written in GJS, it is important to understand that GJS is simply JavaScript bindings for the existing GNOME platform APIs. This means many of the classes and functions you will use are already documented in the GNOME API documentation.
The guides and tutorials for extensions are now available on gjs.guide, including:
Documentation
This documentation is best for those already familiar with GObject in C or Python, but unfamiliar with how to use it in JavaScript.
- The GJS test suite is probably the most thorough example of available features and usage available.
GNOME API Documentation for GJS
This documentation is generated from the same source as the C documentation, but formatted with JavaScript grammar and types.
- The GNOME Shell source contains many re-usable classes and functions as well as plenty of examples of how they can be used.
LookingGlass is a tool that can be used to inspect and debug GNOME Shell while it is running, including point-and-click inspection. It is NOT a stepping debugger like gdb.
Tools
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.
Older Information
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
Getting Help
Ask on discourse.gnome.org using the extensions tag
Ask on StackOverflow using the gnome-shell-extensions and/or gjs tags
- Ask in the extensions IRC/Matrix room