Skip to content

Installation

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

Installation

Better Tray Icons can be installed three ways: from the GNOME Extensions website, from a release archive, or built locally with the Makefile.

Prerequisites

  • GNOME Shell on Wayland. See the README for supported versions. X11 sessions are not supported.
  • A regular user account with permission to install extensions.

Before enabling Better Tray Icons, disable any other tray or AppIndicator extension. They fight over the same DBus names. The conflicting UUIDs are listed in the README.

From the GNOME Extensions website

The easy path for everyday users.

Extension Manager (recommended)

Extension Manager is a Flatpak that handles browse, install, configure, and update in one app. Works on every distribution with Flatpak, no browser plugin needed.

flatpak install flathub com.mattjakeman.ExtensionManager

Open it, switch to Browse, search for Better Tray Icons, click Install.

Through the browser

Open the Better Tray Icons page and toggle the install switch. Needs the GNOME Browser Connector add-on plus the chrome-gnome-shell or gnome-browser-connector system package.

From a release archive

Useful for installing a specific version or working offline. Grab the EGO-compatible ZIP directly from the latest release:

curl -L -o BetterTrayIcons@nexaknight.com.zip \
  https://github.com/nexaknight/BetterTrayIcons/releases/latest/download/BetterTrayIcons@nexaknight.com.zip

Or browse the Releases page and grab BetterTrayIcons@nexaknight.com.zip under Assets (not the auto-generated source archives).

Then install:

gnome-extensions install BetterTrayIcons@nexaknight.com.zip --force

Log out and back in, then enable:

gnome-extensions enable BetterTrayIcons@nexaknight.com

This installs into ~/.local/share/gnome-shell/extensions/BetterTrayIcons@nexaknight.com/ for the current user only.

Build it yourself with the Makefile

Want to build the latest from main without waiting for a release? Or just prefer cloning over downloading? The Makefile handles it.

Tooling

  • git
  • glib-compile-schemas (from glib2 / libglib2.0-dev-bin)
  • gettext for msgfmt
  • node and npm
  • make (usually preinstalled)

Build and install

git clone https://github.com/nexaknight/BetterTrayIcons
cd BetterTrayIcons
make install

That builds the EGO-compatible ZIP and installs it for the current user. Log out and back in, then enable:

gnome-extensions enable BetterTrayIcons@nexaknight.com

Other Makefile targets

Target What it does
make pack Build the ZIP only, don't install
make test Run lint, schema, and translation checks
make clean Remove generated files
make uninstall Remove the locally installed extension
make help Show all targets

Updating

git pull
make install

Then log out and back in.

On modern GNOME Shell (Wayland), there's no in-session reload. Logout and login is the supported path.

Verifying the installation

gnome-extensions info BetterTrayIcons@nexaknight.com

Shows metadata, install path, and whether the extension is active.

Live shell logs:

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

Updating

  • Extensions website installs update automatically.
  • Release-archive installs: download the new ZIP, reinstall with --force, log out and back in.
  • Local builds: git pull && make install.

Uninstalling

Through Extension Manager: click the extension, choose Uninstall. Files go, dconf settings stay so a reinstall picks up where you left off.

For local builds, you can also use:

make uninstall

To also remove the stored settings:

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

Log out and back in.

Troubleshooting

  • Extension does not appear after install. Make sure you logged out and back in, and your GNOME version is in the supported range (gnome-shell --version).
  • Tray button is visible but icons do not show. Check the Applications tab in the preferences. Hidden apps and missing icons are listed there.
  • Settings do not stick across reloads. Confirm gschemas.compiled exists under schemas/ for local builds.
  • For anything else, see the Bug Reporting Guidelines and attach debug logs from the preferences window.

Want to contribute?

If you're planning to work on the code, translations, or docs (not just install it), see the Contributing guide for the proper dev setup.

Clone this wiki locally