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 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:

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, including:


  • GJS Usage Documentation

    • This documentation is best for those already familiar with GObject in C or Python, but unfamiliar with how to use it in JavaScript.

  • GJS Test Suite

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

  • GNOME Shell JavaScript source

    • The GNOME Shell source contains many re-usable classes and functions as well as plenty of examples of how they can be used.
  • LookingGlass Inspector

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


As of GNOME Shell 3.34, there is a new gnome-extensions command-line tool for working with extensions:

$ gnome-extensions
  gnome-extensions COMMAND [ARGS…]

  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:

Getting Help

Projects/GnomeShell/Extensions (last edited 2021-11-27 03:28:17 by AndyHolmes)