This page is an overview of GNOME Shell's architecture, from the perspective of GNOME Shell extensions. It is intended to help clarify how extensions fit into the larger picture.


Clutter and St

Unlike most GNOME applications, Mutter and GNOME Shell are both built on the Clutter toolkit which is more abstract than GTK.

Clutteropen in new window widgets are called Actorsopen in new window and have all the basic properties and signals you would expect from a base widget. Actors can contain other actors using several layout managers and have built-in support for animations and other effects.

Stopen in new window builds on Clutter to provide more complex widgets like buttons, icons, text entries and scrollable areas. It also adds support for CSS so the style of widgets can be changed programmatically or from a stylesheet.


In Wayland sessions Mutteropen in new window implements the compositor side of the Wayland protocol, while in X11 sessions it serves as the window manager and compositing manager.

For GNOME Shell extensions, the Metaopen in new window import gives access to displays, workspaces, windows, clipboard selections and more.


Shellopen in new window provides a number of utilities and classes, including the globalopen in new window object. Just as Meta is the library API for Mutter, Shell is effectively the library of GNOME Shell itself.


Like most of the GNOME API, the libraries described above are all written in C. They are made available to GJS by GObject-Introspectionopen in new window, which provides metadata for language bindings and is also used to generate the GNOME API documentationopen in new window.

GNOME Shell's JavaScript codebaseopen in new window uses these libraries to create the user interface you interact with every day, organized into modules. A number of these modules are re-used throughout GNOME Shell and are commonly used in extensions:


GNOME Shell extensions can use or modify anything described above, much like GNOME Shell's JavaScript itself. Once an extension is loaded and enabled, it effectively becomes a part of GNOME Shell.

This means extensions can:

  • Use Mutter to control displays, workspaces and windows
  • Use Clutter & St to create new UI elements
  • Use JavaScript modules to create new UI elements
  • Use any other library supporting GObject-Introspection
  • Access and modify any internal GNOME Shell code
Last Updated: 5/19/2023, 7:28:41 AM
Contributors: Andy Holmes, Evan Welsh, Heewa Barfchin