GNOME Extensions Manager: Safe Usage Guide

This guide shows you how to use the GNOME Extensions Manager app to install, enable, and manage shell extensions without breaking your desktop session. You will learn how to vet extensions before installing, use the app’s built-in safety features, and recover if something goes wrong. No prior experience with extensions is required, but you should be comfortable using the GNOME Settings app.

What You’ll Need

A supported GNOME desktop environment (version 40 or newer is recommended, as the new Extensions Manager relies on the modern extension system).
The GNOME Extensions Manager app installed. On most distributions, it is available through your software center (search for “Extensions”) or via your package manager (e.g., sudo apt install gnome-extensions-app on Debian/Ubuntu, sudo dnf install gnome-extensions-app on Fedora).
An internet connection to browse and download extensions from the GNOME Extensions website.
Your system’s package manager or software center may also need to be up-to-date to ensure compatibility.

Step-by-Step

Open the Extensions Manager app. You can find it in your application grid (usually by pressing the Super key and searching for “Extensions”). The window will show a list of installed extensions on the left and details about the selected one on the right.
Browse or search for an extension. Click the “Browse” button at the top of the window (it looks like a compass or a grid icon). This opens a view of popular and featured extensions from the GNOME Extensions website. Use the search bar to find a specific one by name or keyword.
Check the extension’s details before installing. Click on any extension to see its full page. Pay attention to:
- Compatibility: The page will show which GNOME Shell versions it supports. Make sure your version is listed. If not, the extension may not work correctly.
- Rating and reviews: Look at the star rating and read recent reviews. A low rating or many complaints about crashes or bugs is a red flag.
- Last updated: Check when the extension was last updated. An extension that hasn’t been updated in over a year may not work with the latest GNOME Shell.
- Author: Prefer extensions from well-known or reputable developers. You can click the author’s name to see their other extensions.
Install the extension. On the extension’s page, toggle the switch to “On” (or click the “Install” button if present). The app will download and install the extension. A confirmation dialog may appear; click “Install” to proceed.
Enable the extension. After installation, the extension will appear in your installed extensions list. If it is not automatically enabled, click the toggle switch next to its name to turn it on.
Test the extension. Immediately after enabling, try the feature it provides. For example, if it adds a clock to the top bar, check that the clock appears and updates. If it adds a menu, open it and see if it works. If anything looks wrong, disable the extension right away.
Adjust extension settings (if any). Some extensions have their own settings. Look for a gear icon or a “Settings” button next to the extension in the list. Click it to open a separate settings window. Change options as desired, and they will apply immediately.
Disable or remove an extension you no longer need. To turn it off temporarily, toggle its switch off. To remove it completely, click the trash can icon next to the extension’s name. A confirmation dialog will ask if you are sure; click “Remove” to uninstall it.
Update extensions regularly. The Extensions Manager will show a notification when updates are available. You can also check manually by clicking the “Updates” tab (if available) or by refreshing the browse view. Keeping extensions updated reduces the risk of breakage after a GNOME Shell update.

Common Mistakes

Installing extensions that are not compatible with your GNOME Shell version. This is the most common cause of problems. Always check the compatibility list on the extension’s page before installing.
Enabling too many extensions at once. Each extension adds code that runs in your shell. Too many can slow down your desktop or cause conflicts. Install and enable one at a time to isolate any issues.
Ignoring warnings from the app. If the Extensions Manager shows a warning that an extension is “not compatible” or “may not work,” do not force-enable it. The warning is there for a reason.
Not testing after a GNOME Shell update. After a system update that changes the GNOME Shell version, some extensions may break. Check your extensions after such updates and disable any that are not working.
Deleting the extension’s data folder manually. If you want to remove an extension, use the Extensions Manager’s remove button. Manually deleting files in ~/.local/share/gnome-shell/extensions can leave your system in an inconsistent state.

Tips

Use the “User Themes” extension carefully. This extension is a common source of issues because it loads custom shell themes. Only enable it if you have a compatible theme installed and you know how to revert.
Create a backup of your extensions list. Before a major system update, you can note down which extensions you have enabled. This makes it easier to re-enable them if the update resets things.
Check the extension’s documentation. Many extensions have a README or a wiki page linked from their extension page. This often contains troubleshooting tips and known issues.
Use the “Reset” option in the Extensions Manager. If an extension is misbehaving but you don’t want to remove it, look for a “Reset” button in its settings. This restores the extension’s default settings without uninstalling it.
Keep your system updated. GNOME Shell and the Extensions Manager receive regular updates. Installing them promptly reduces the window in which an extension might break due to an outdated shell.

Troubleshooting

An extension is enabled but has no effect. First, check that the extension is actually enabled (the toggle is on). Then, look at the extension’s settings to see if there is a master switch or a configuration option that needs to be set. If it still doesn’t work, try disabling and re-enabling it. If that fails, remove it and reinstall it.

The top bar or desktop looks broken after enabling an extension. This usually means the extension is incompatible or buggy. Open the Extensions Manager (if you can) and toggle the extension off immediately. If you cannot open the app because the shell is unresponsive, you can press Alt+F2, type r, and press Enter to restart the GNOME Shell. This will reload the shell without logging out, and the problematic extension will be disabled temporarily.

An extension worked before but stopped after a system update. This is almost always due to a GNOME Shell version change. The extension may be listed as “incompatible” in the Extensions Manager. If so, you have two options: wait for the extension author to update it, or remove it and look for an alternative. Do not try to force-enable it, as this can cause crashes.

You see a “Failed to load extension” error. This error usually appears in the Extensions Manager or in the system log. It means the extension’s code could not be loaded. Try removing and reinstalling the extension. If the error persists, the extension is likely broken and you should not use it.

The Extensions Manager itself won’t open or crashes. First, try restarting your session (log out and back in). If that doesn’t help, check if your system has a newer version of the app available. As a last resort, you can reset the app’s configuration by removing its settings file (usually in ~/.config), but this will reset all your extension preferences.

You installed an extension but it doesn’t appear in the list. Make sure you are looking at the “Installed” tab in the Extensions Manager. If it’s not there, the installation may have failed. Try installing it again. Also, check that the extension is installed for the correct user (your user, not root).

Frequently Asked Questions

Q: Is it safe to install any extension from the GNOME Extensions website?
A: No. Extensions run with the same privileges as your user session, so a malicious or buggy extension could access your files or crash your desktop. Stick to popular, well-reviewed extensions from known authors, and always check the compatibility and update date.

Q: Can I install extensions without the Extensions Manager app?
A: Yes, you can install them from the GNOME Extensions website using a web browser, but you need a browser integration add-on. The Extensions Manager app is the recommended and safest way because it handles installation, updates, and compatibility checks automatically.

Q: How do I know which GNOME Shell version I have?
A: Run gnome-shell --version in a terminal. The output will show something like GNOME Shell 42.5. Use this number when checking extension compatibility.

Q: Will my extensions break after every GNOME update?
A: Not every update, but major GNOME Shell releases (e.g., from 41 to 42) often break extensions because the internal APIs change. Minor updates (e.g., 42.1 to 42.2) rarely cause issues. Always check your extensions after a major update.

Q: What should I do if an extension crashes my entire desktop?
A: Press Alt+F2, type r, and press Enter to restart the shell. Then open the Extensions Manager and disable the problematic extension. If you cannot get the shell to respond, you may need to log out and log back in from the login screen.

Q: Can I have multiple versions of the same extension installed?
A: No, the system only supports one version per extension ID. If you try to install a different version, it will overwrite the existing one. Always remove the old version before installing a new one if you are switching from a different source.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →