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.

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

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.

Configuring Extensions

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.

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 (see Documentation below).

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.

Tutorials

  • Beginner's Tutorial

    • 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.
  • Migrating Shell Classes

    • As GJS has improved, many classes have been refactored as proper GObject classes, which changes the way they are subclassed. This is a short guide to migrating GNOME Shell objects from native JavaScript classes to GObject classes.

  • Tips On Memory Management

    • 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.

Documentation

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:

Debugging extensions

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).

Getting Help

Projects/GnomeShell/Extensions (last edited 2020-08-07 22:44:40 by AndyHolmes)