Table of Contents

Gnome - Extensions - metadata.json

metadata.json is a mandatory file of every extension.


A minimal example, with only mandatory fields

metadata.json
{
    "uuid": "example@blah",
    "name": "Example",
    "description": "This is an example extension.",
    "shell-version": [ "3.38", "40" ],
    "url": "https://sharewiz.net/gnome/extensions/example",
    "version": 1
}

A comprehensive example, including optional fields

metadata.json
{
    "uuid": "example@blah",
    "name": "Example",
    "description": "This is an example extension.",
    "shell-version": [ "3.38", "40" ],
    "url": "https://sharewiz.net/gnome/extensions/example",
    "version": 1
    "session-modes": ["user", "unlock-dialog"],
    "settings-schema": "org.gnome.shell.extensions.example",
    "gettext-domain": "example@blah",
}

Mandatory Fields

uuid

A globally-unique identifier for your extension, made of two parts separated by @.

NOTE: An extension must be installed to a directory with the same name as uuid+ to be recognized by GNOME Shell.

~/.local/share/gnome-shell/extensions/example@blah/

name

A short, descriptive name for the extension.


description

A relatively short description of the extension.

NOTE: Line breaks and tabs can be inserted by using \n and \t escape sequences.


shell-version

An array of strings describing the GNOME Shell versions that an extension supports.

NOTE: It must include at least one entry or the extension will be uninstallable.

  • For versions up to and including GNOME 3.38, this should have a major and minor component such as “3.38”.
  • Starting with GNOME 40, it should simply be the major version, such as “40” or “41”.
  • GNOME Shell has a configuration setting, disable-extension-version-validation, which controls whether unsupported extensions can be loaded.
    • Before GNOME 40 this was true by default (users could install extensions regardless of the shell-version), but because of the major changes it is now false by default.

url

A URL for an extension, where the code can be found and issues can be reported.

NOTE: It is required for extensions submitted to https://extensions.gnome.org/ to have a valid URL.


version

The version of the extension.

NOTE: As known to the GNOME Extensions website, and MUST be a whole number like 1.

  • It is not a semantic version like 1.1 or a string like “1”.
  • This version is automatically incremented by the GNOME Extensions website with each submission.

Optional Fields

gettext-domain

A Gettext translation domain, used by the ExtensionUtils.initTranslations() convenience method to create a object with methods for marking and retrieving string translations in an extension.

NOTE: The domain should be unique to your extension and the easiest choice is to use the UUID from your extension, such as example@blah.

  • See the Translations page.

settings-schema

A Gio.SettingsSchema ID, used by the ExtensionUtils.getSettings() convenience method to create a Gio.Settings object for an extension.

NOTE: By convention, the schema ID for extensions all start with the string org.gnome.shell.extensions with the extension ID as a unique identifier, such as org.gnome.shell.extensions.example.

  • See the Preferences page.

session-modes

An array of strings describing the GNOME Shell session modes that the extension supports.

NOTE: Almost all extensions will only use the user session mode, which is the default if this field is not present.

WARNING: This field was added in GNOME 42.

The current possible session modes are:

NOTE: Extensions that want to support other session modes must provide a justification to be approved during review for distribution from the GNOME Extensions website.