Mastodon Skip to content
BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild

gnome-extensions

The gnome-extensions module can be used to install Gnome extensions inside system directory.
It also supports uninstallation as well, for extensions which are not installed through OS package manager.

This module is universally compatible with all distributions which ship Gnome, as it’s not tied to specific distribution packaging format for installing extensions.

Almost all Gnome extensions are compatible for installation.

Thanks to https://extensions.gnome.org which provides releases of extensions as zips, it is very easy to maintain this module configuration.

What does this module do?

  • It checks the current Gnome version of your image
  • It parses the extension name input from module recipe file
  • It processes the jsquery from https://extensions.gnome.org using the extension name input,
    which contains useful info about latest extension version compatible with Gnome version of your image
  • Download archive URL is formed based on the info above
  • Downloaded extension archive is then extracted to temporary directory
  • All of its extracted files are copied to the appropriate final directories
    (/usr/share/gnome-shell/extensions, /usr/share/glib-2.0/schemas, & /usr/share/locale)
  • Gschema is finally compiled to include the copied extensions schemas to its database

Uninstallation step is performed similarly, except it obviously removes files from the mentioned final directories.

Usage

Extension Installation

By default, latest extension version compatible with Gnome version of your image, is installed.

How to install extensions using the module:

  1. Go to https://extensions.gnome.org or preferably Extension Manager application
  2. Search for the extension that you want to install and open its extension page
  3. If browsing through https://extensions.gnome.org, select the correct GNOME shell version, which matches the GNOME shell version of your image
    • The command gnome-shell --version can be used to get the GNOME version of a running system. If there is no GNOME shell version of the extension that matches the GNOME version of your image, that means that extension is not compatible
  4. Copy the extension name & input it in module recipe (it is case-sensitive, so be sure that you copied it correctly)

An extension might need additional system dependencies in order to function.
In that case, you should install the required dependencies before the gnome-extensions module is ran.
Information about the required dependencies (if any) are usually on the extension’s page.

Extension Uninstallation

Extension uninstallation can be useful to uninstall extensions from the base image,
which are not installed through OS package manager (like extensions installed from gnome-extensions module).

However, if extensions in the base image are installed through OS package manager, than they should be removed through it instead.

How to uninstall extensions using the module:

  1. Go to Gnome Extensions app, https://extensions.gnome.org/local/ or Extension Manager application
  2. List of installed system extensions should be presented
  3. Copy the extension name & input it in module recipe (it is case-sensitive, so be sure that you copied it correctly)

Known issues

Some extensions complain about missing gschema.compiled file

This is a rarity, but some extensions might complain about this one, due to the way they are programmed with hard-coded gschema locations.
Most extensions which follow Gnome extension standards don’t have this issue.

If you get the error similar to this one (Fly-Pie extension example):
GLib.FileError: Failed to open file “/usr/share/gnome-shell/extensions/flypie@schneegans.github.com/schemas/gschemas.compiled”: open() failed: No such file or directory

Then please open the issue in BlueBuild Modules GitHub repo with the affecting extension, as it’s trivial to fix.
https://github.com/blue-build/modules/issues/new

Example configuration

type: gnome-extensions
install:
  - Night Theme Switcher
  - Blur my Shell # Notice how extension is named "Blur my Shell" & not "Blur My Shell"?
                  # Name is case-sensitive, so check if extension name is typed correctly
  - AppIndicator and KStatusNotifierItem Support
  - 307 # Dash-to-Dock
        # https://extensions.gnome.org/extension/307/dash-to-dock/
        # You can also specify PK ID number from the extension URL,
        # if you encounter the scenario where there are multiple extensions with the same name.
        # You don't need to look & search for this scenario, since module will automatically fail & inform you to put PK ID number instead
uninstall:
  - GSConnect # Uninstall step here should be used only for the extensions
              # which are not installed through OS package manager in the base image,
              # like extensions installed from gnome-extensions module

Configuration options

install: (optional array)

List of GNOME extensions to install. (case sensitive extension names or extension IDs from https://extensions.gnome.org/)

uninstall: (optional array)

List of system GNOME extensions to uninstall. Only use this to remove extensions not installed by your package manager. Those extensions should be uninstalled using the package manager instead.