Skip to content

Installation

Jump to bottom
NexaKnight edited this page May 13, 2026 · 4 revisions

Better Tray Icons can be installed in three ways: through the GNOME Extensions website with a single click, from a downloaded release archive, or straight from the git source for development. This page walks through each path and covers a few things that come up afterwards, like reloading the shell and uninstalling cleanly.

Prerequisites

  • GNOME Shell running on Wayland. Check the README for the currently supported version range, as it gets updated whenever new GNOME releases are added or dropped. X11 sessions are not supported.
  • Permission to install GNOME Shell extensions, which is the default on a regular user account.

Before enabling the extension, disable any other tray or AppIndicator extension on your system. Both would fight over the same DBus names and behave unpredictably side by side. The conflicting UUIDs are listed in the project README.

Installing from the GNOME Extensions website

This is the recommended path for everyday use.

Extension Manager (recommended)

The fastest way is the [Extension Manager](https://flathub.org/en/apps/com.mattjakeman.ExtensionManager) Flatpak by Matt Jakeman. It bundles browse, install, configure and update into one app and works on every distribution that ships Flatpak, no browser plugin required.

  1. Install it from Flathub: 
    flatpak install flathub com.mattjakeman.ExtensionManager
  2. Open Extension Manager and switch to the Browse tab.
  3. Search for Better Tray Icons and click Install. The extension is enabled right away.

Updates show up under the Installed tab once a new release is published.

Through the browser

If you'd rather not install another app, the extensions site supports installation directly from the browser. This needs the GNOME Browser Connector add-on plus the matching chrome-gnome-shell or gnome-browser-connector system package. After both are in place, open the [Better Tray Icons page](https://extensions.gnome.org/) and toggle the install switch.

The built-in GNOME Extensions app (gnome-extensions-app) does not browse the website on its own. It's useful for toggling, configuring and uninstalling extensions you already have, but it cannot install new ones from extensions.gnome.org directly.

Installing from a release archive

Useful when you want a specific version or you are offline.

  1. Open the [Releases page](../../releases) on GitHub and download the .zip of the version you want.
  2. Install the archive with gnome-extensions install: 
    gnome-extensions install ~/Downloads/BetterTrayIcons-vX.Y.Z.zip --force
    The --force flag overwrites an older version of the same UUID if one is already present.
  3. Reload the shell. See [Reloading the shell](#reloading-the-shell) below.
  4. Enable the extension: 
    gnome-extensions enable BetterTrayIcons@nexaknight.com

This installs into ~/.local/share/gnome-shell/extensions/BetterTrayIcons@nexaknight.com. The extension is only available to the current user.

Installing the development version

For working on the code, translations or documentation.

Tooling

  • git to clone the repository.
  • glib-compile-schemas for the GSettings schema. Comes with glib2 or libglib2.0-dev-bin depending on the distribution.
  • gettext for msgfmt. Already installed on most distributions.
  • node and npm for the project scripts. Only needed if you intend to run npm test or compile locales.

Steps

  1. Clone the repository directly into the GNOME Shell extensions directory, using the UUID as the folder name: 
    UUID=BetterTrayIcons@nexaknight.com
git clone https://github.com/nexaknight/BetterTrayIcons "$HOME/.local/share/gnome-shell/extensions/$UUID"
cd "$HOME/.local/share/gnome-shell/extensions/$UUID"
  2. Compile the GSettings schema: 
    glib-compile-schemas schemas/
    This produces schemas/gschemas.compiled, which GNOME loads at startup.
  3. Install the dev dependencies (only needed once, and only for linting and pre-commit checks): 
    npm install
  4. Compile the translation files: 
    npm run compile-locales
    This generates locale/<lang>/LC_MESSAGES/bettertrayicons.mo from every po/<lang>.po.
  5. Reload the shell. See [Reloading the shell](#reloading-the-shell) below.
  6. Enable the extension: 
    gnome-extensions enable BetterTrayIcons@nexaknight.com

Iterating on changes

Most code changes take effect after a shell reload. Schema changes need a fresh glib-compile-schemas schemas/ first. Translation changes need npm run compile-locales first.

For shell-side iterations without restarting your full session, a nested GNOME Shell can save a lot of time:

dbus-run-session -- gnome-shell --nested --wayland

The nested shell runs in its own window, picks up your working tree, and can be closed without affecting your main session.

Reloading the shell

GNOME Shell loads extensions at session start, so changes don't show up until the shell reloads. Pick the method that fits your setup.

  • Log out and back in of your GNOME session. This is the supported way on Wayland.
  • Nested shell for development. Have a look at the previous section.

Pure restart commands like Alt+F2 → r only exist on X11 sessions, which this extension does not target.

Verifying the installation

After enabling, you should see the toggle button appear in the panel as soon as a tray-using application starts. To confirm GNOME picked up the extension at all:

gnome-extensions info BetterTrayIcons@nexaknight.com

This prints the metadata, the install path and whether the extension is currently active.

To watch the live log output of the shell:

journalctl --user -f -o cat /usr/bin/gnome-shell

Enable Debug Mode on the General tab of the preferences for more verbose output. The Bug Reporting Guidelines explain the full debug workflow.

Updating

  • Extensions website installs update automatically when a new release is published. The GNOME Extensions app will notify you and offer to apply the update.
  • Release-archive installs need the new archive downloaded and re-installed with gnome-extensions install ... --force, followed by a shell reload.
  • Development installs update by running git pull in the extension directory, re-compiling schemas and locales as needed, then reloading the shell.

Uninstalling

The cleanest way is through the GNOME Extensions app. Open it, click the extension, and choose Uninstall. This removes the extension files but keeps your saved settings in dconf, so reinstalling later picks up where you left off.

To also remove the stored settings:

dconf reset -f /org/gnome/shell/extensions/bettertrayicons/

For a development install, just delete the directory:

rm -rf "$HOME/.local/share/gnome-shell/extensions/BetterTrayIcons@nexaknight.com"

Reload the shell after either path.

Troubleshooting

  • The extension does not appear after install. Make sure the shell has been reloaded and the GNOME version on your machine falls within the supported range (gnome-shell --version).
  • The tray button is visible but icons do not show. Check the Applications tab in the preferences. Hidden apps or missing detected icons will be listed there.
  • Settings do not stick across reloads. Confirm that gschemas.compiled exists under schemas/ for development installs. The Extensions website install builds it automatically.
  • Anything else worth a bug report goes through the [Bug/Issue Reporting Guidelines](Bug-Issue-Reporting-Guidelines), with debug logs from the preferences window attached.Better Tray Icons can be installed in three ways: through the GNOME Extensions website with a single click, from a downloaded release archive, or straight from the git source for development. This page walks through each path and covers a few things that come up afterwards, like reloading the shell and uninstalling cleanly.

Prerequisites

  • GNOME Shell running on Wayland. Check the README for the currently supported version range, as it gets updated whenever new GNOME releases are added or dropped. X11 sessions are not supported.
  • Permission to install GNOME Shell extensions, which is the default on a regular user account.

Before enabling the extension, disable any other tray or AppIndicator extension on your system. Both would fight over the same DBus names and behave unpredictably side by side. The conflicting UUIDs are listed in the project README.

Installing from the GNOME Extensions website

This is the recommended path for everyday use.

Extension Manager (recommended)

The fastest way is the [Extension Manager](https://flathub.org/en/apps/com.mattjakeman.ExtensionManager) Flatpak by Matt Jakeman. It bundles browse, install, configure and update into one app and works on every distribution that ships Flatpak, no browser plugin required.

  1. Install it from Flathub: 
    flatpak install flathub com.mattjakeman.ExtensionManager
  2. Open Extension Manager and switch to the Browse tab.
  3. Search for Better Tray Icons and click Install. The extension is enabled right away.

Updates show up under the Installed tab once a new release is published.

Through the browser

If you'd rather not install another app, the extensions site supports installation directly from the browser. This needs the GNOME Browser Connector add-on plus the matching chrome-gnome-shell or gnome-browser-connector system package. After both are in place, open the [Better Tray Icons page](https://extensions.gnome.org/) and toggle the install switch.

The built-in GNOME Extensions app (gnome-extensions-app) does not browse the website on its own. It's useful for toggling, configuring and uninstalling extensions you already have, but it cannot install new ones from extensions.gnome.org directly.

Installing from a release archive

Useful when you want a specific version or you are offline.

  1. Open the [Releases page](../../releases) on GitHub and download the .zip of the version you want.
  2. Install the archive with gnome-extensions install: 
    gnome-extensions install ~/Downloads/BetterTrayIcons-vX.Y.Z.zip --force
    The --force flag overwrites an older version of the same UUID if one is already present.
  3. Reload the shell. See [Reloading the shell](#reloading-the-shell) below.
  4. Enable the extension: 
    gnome-extensions enable BetterTrayIcons@nexaknight.com

This installs into ~/.local/share/gnome-shell/extensions/BetterTrayIcons@nexaknight.com. The extension is only available to the current user.

Installing the development version

For working on the code, translations or documentation.

Tooling

  • git to clone the repository.
  • glib-compile-schemas for the GSettings schema. Comes with glib2 or libglib2.0-dev-bin depending on the distribution.
  • gettext for msgfmt. Already installed on most distributions.
  • node and npm for the project scripts. Only needed if you intend to run npm test or compile locales.

Steps

  1. Clone the repository directly into the GNOME Shell extensions directory, using the UUID as the folder name: 
    UUID=BetterTrayIcons@nexaknight.com
git clone https://github.com/nexaknight/BetterTrayIcons "$HOME/.local/share/gnome-shell/extensions/$UUID"
cd "$HOME/.local/share/gnome-shell/extensions/$UUID"
  2. Compile the GSettings schema: 
    glib-compile-schemas schemas/
    This produces schemas/gschemas.compiled, which GNOME loads at startup.
  3. Install the dev dependencies (only needed once, and only for linting and pre-commit checks): 
    npm install
  4. Compile the translation files: 
    npm run compile-locales
    This generates locale/<lang>/LC_MESSAGES/bettertrayicons.mo from every po/<lang>.po.
  5. Reload the shell. See [Reloading the shell](#reloading-the-shell) below.
  6. Enable the extension: 
    gnome-extensions enable BetterTrayIcons@nexaknight.com

Iterating on changes

Most code changes take effect after a shell reload. Schema changes need a fresh glib-compile-schemas schemas/ first. Translation changes need npm run compile-locales first.

For shell-side iterations without restarting your full session, a nested GNOME Shell can save a lot of time:

dbus-run-session -- gnome-shell --nested --wayland

The nested shell runs in its own window, picks up your working tree, and can be closed without affecting your main session.

Reloading the shell

GNOME Shell loads extensions at session start, so changes don't show up until the shell reloads. Pick the method that fits your setup.

  • Log out and back in of your GNOME session. This is the supported way on Wayland.
  • Nested shell for development. Have a look at the previous section.

Pure restart commands like Alt+F2 → r only exist on X11 sessions, which this extension does not target.

Verifying the installation

After enabling, you should see the toggle button appear in the panel as soon as a tray-using application starts. To confirm GNOME picked up the extension at all:

gnome-extensions info BetterTrayIcons@nexaknight.com

This prints the metadata, the install path and whether the extension is currently active.

To watch the live log output of the shell:

journalctl --user -f -o cat /usr/bin/gnome-shell

Enable Debug Mode on the General tab of the preferences for more verbose output. The Bug Reporting Guidelines explain the full debug workflow.

Updating

  • Extensions website installs update automatically when a new release is published. The GNOME Extensions app will notify you and offer to apply the update.
  • Release-archive installs need the new archive downloaded and re-installed with gnome-extensions install ... --force, followed by a shell reload.
  • Development installs update by running git pull in the extension directory, re-compiling schemas and locales as needed, then reloading the shell.

Uninstalling

The cleanest way is through the GNOME Extensions app. Open it, click the extension, and choose Uninstall. This removes the extension files but keeps your saved settings in dconf, so reinstalling later picks up where you left off.

To also remove the stored settings:

dconf reset -f /org/gnome/shell/extensions/bettertrayicons/

For a development install, just delete the directory:

rm -rf "$HOME/.local/share/gnome-shell/extensions/BetterTrayIcons@nexaknight.com"

Reload the shell after either path.

Troubleshooting

  • The extension does not appear after install. Make sure the shell has been reloaded and the GNOME version on your machine falls within the supported range (gnome-shell --version).
  • The tray button is visible but icons do not show. Check the Applications tab in the preferences. Hidden apps or missing detected icons will be listed there.
  • Settings do not stick across reloads. Confirm that gschemas.compiled exists under schemas/ for development installs. The Extensions website install builds it automatically.
  • Anything else worth a bug report goes through the [Bug/Issue Reporting Guidelines](Bug-Issue-Reporting-Guidelines), with debug logs from the preferences window attached.

Clone this wiki locally