Gnome - Extensions - metadata.json

metadata.json is a mandatory file of every extension.

It contains basic information about the extension such as its UUID, name and description.
Some fields are mandatory, but there are a number of other optional fields too that metadata.json may contain.

A minimal example, with only mandatory fields

{
    "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 @.

Each part must only container letters, numbers, period (.), underscore (_) and hyphen (-).
- The first part should be a short string like “click-to-focus”.
- The second part must be some namespace under your control, such as username.github.io.
- Common examples are click-to-focus@username.github.io and adblock@account.gmail.com.

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:

user: Extensions that specify this key run during active user sessions.
- If no other session modes are specified, the extension will be enabled when the session is unlocked and disabled when it locks.
unlock-dialog: Extensions that specify this key are allowed to run, or keep running, on the lock screen.
gdm: Extensions that specify this key are allowed to run, or keep running, on the login screen.
- This session mode is only available for system extensions that are enabled for the gdm user.

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.

Wiki

Table of Contents