GNOME Extensions
You installed a new extension to add a dock to your panel, clicked the toggle, and GNOME Shell vanished. The screen flickered back to the login prompt. Or maybe you upgraded Fedora, and now your favorite extension won't load, leaving you with a bare desktop and no way to close windows. Extensions are powerful, but they run inside the shell process. A bad extension can take the whole desktop down with it.
What's actually happening
GNOME Shell is a single process that draws the panel, handles window switching, and manages the overview. Extensions are JavaScript snippets that hook into this process. They don't run in isolation. When an extension loads, it executes code directly inside the shell. If that code throws an error or conflicts with the shell's internal API, the shell can crash or refuse to start the extension.
Think of extensions like plugins for a critical service. You are adding complexity to a tightly integrated system. Fedora ships with a clean, stable GNOME. Extensions modify that baseline. Treat them with the same caution you would apply to kernel modules or systemd unit overrides.
Install the Extensions Manager App
The Extensions Manager app is the safest entry point. It shows what is installed, lets you toggle state, and provides configuration dialogs for extensions that support them. It also protects you from accidentally deleting files, since GNOME manages extension state by renaming directories.
Here's how to install the manager and verify it works.
sudo dnf install gnome-extensions-app
# Installs the GUI tool to manage extensions without touching the browser
# Provides a reliable interface for enabling, disabling, and configuring extensions
Open the app from the Activities overview. It lists installed extensions and lets you enable, disable, or configure each one. The app reads the state from the system and updates it via D-Bus.
Install the app first. It saves you from guessing UUIDs later.
Install Extensions from extensions.gnome.org
The browser connector bridges the web interface at extensions.gnome.org with your local system. Once installed, you add the browser add-on, and the website gains a toggle switch for each extension. This is the standard way to browse the community repository.
Here's how to set up the connector and browser add-on.
sudo dnf install gnome-browser-connector
# Installs the D-Bus bridge that lets the website talk to GNOME Shell
# Required for the toggle switch on extensions.gnome.org to function
Install the companion browser add-on from the link shown at https://extensions.gnome.org. The add-on communicates with the connector package. Browse the site and use the toggle switch to install or remove extensions instantly. The connector installs files to ~/.local/share/gnome-shell/extensions.
Keep the browser add-on updated. An old connector breaks the toggle switch.
Use DNF for Packaged Extensions
Fedora packages some popular extensions. Using dnf gives you dependency resolution and updates alongside your system. The browser connector won't show these as "installed" from the website because they live in the package manager. Packaged extensions are often more stable and receive updates when you run dnf upgrade.
Here's how to search for and install a packaged extension.
dnf search gnome-shell-extension
# Searches Fedora repositories for available extension packages
# Helps you find official packages before browsing the community site
sudo dnf install gnome-shell-extension-dash-to-panel
# Installs the extension from Fedora repos, ensuring dependency tracking
# Places files in /usr/share/gnome-shell/extensions for system-wide use
After installing a packaged extension, enable it with gnome-extensions enable or via the Extensions app. The package manager handles the files; the extension manager handles the state.
Check the repos before the website. Packaged extensions update with your system.
Use the gnome-extensions CLI
The gnome-extensions command works over SSH or in a TTY. It uses UUIDs to identify extensions. This is essential for automation or recovery when the GUI is unavailable. The CLI reads the same state database as the app and the browser connector.
Here's how to list, enable, and disable extensions from the command line.
gnome-extensions list --details
# Lists all installed extensions with their UUID, name, and enabled state
# Useful for scripting and identifying the exact UUID of an extension
gnome-extensions enable dash-to-dock@micxgx.gmail.com
# Enables the extension by its unique identifier
# The UUID format is name@author-domain, which GNOME uses for lookup
gnome-extensions disable dash-to-dock@micxgx.gmail.com
# Disables the extension without removing files
# GNOME renames the extension directory by appending .disabled
The UUID contains the author domain. This helps when multiple extensions share a similar name. The CLI doesn't care about pretty names; it only recognizes the UUID.
Know the UUID. The CLI doesn't care about pretty names.
Where extensions live on disk
Fedora separates user data from system data. The browser connector drops files in ~/.local/share/gnome-shell/extensions. DNF installs to /usr/share/gnome-shell/extensions. When you disable an extension, GNOME renames the directory by appending .disabled. This is why you don't delete files manually. The manager handles the state.
Here's how to inspect the extension directories.
ls ~/.local/share/gnome-shell/extensions
# Lists user-installed extensions to verify the directory structure
# Shows directories named by UUID, or UUID.disabled if disabled
ls /usr/share/gnome-shell/extensions
# Lists system-wide extensions installed via DNF
# These are managed by the package manager and persist across users
User extensions override system extensions with the same UUID. If you install an extension via DNF and then via the browser, the user version takes precedence. This can cause confusion if the versions differ.
Don't delete extension files manually. Use the manager or CLI to change state.
Troubleshoot a Broken Extension
A faulty extension can crash GNOME Shell. If the desktop becomes unresponsive or you get kicked back to the login screen, you need to disable extensions to regain access. Switch to a TTY with Ctrl+Alt+F3 or use an SSH session. Disable all user extensions to restore a working desktop.
Here's how to disable all extensions and recover your session.
gsettings set org.gnome.shell disable-user-extensions true
# Disables all user extensions to restore a working desktop session
# This key forces GNOME Shell to skip loading any extensions on restart
gsettings set org.gnome.shell disable-user-extensions false
# Re-enables extensions once you have identified and fixed the issue
# Run this after rebooting or restarting GNOME Shell with Alt+F2, r, Enter
After disabling extensions, restart GNOME Shell or reboot. Once the desktop is stable, re-enable extensions one by one to find the culprit. Check the logs for JavaScript errors. The UUID in the error tells you which extension failed.
Disable all extensions before you reboot. A working TTY is your lifeline.
Read the logs
GNOME Shell logs errors to the journal. Use journalctl to find extension-related messages. The -xe flags add explanatory text and jump to the end, which is faster for debugging. The -u flag filters by unit.
Here's how to check the journal for extension crashes.
journalctl -xeu gnome-shell
# Shows shell logs with explanatory text, jumping to the end
# Filters for the gnome-shell unit to isolate desktop errors
Look for lines containing JS ERROR or Extension error. The log will include the UUID and a stack trace. If you see a specific error, search for that UUID to find the extension.
Here's an example of what a typical extension error looks like in the journal.
JS ERROR: Extension dash-to-dock@micxgx.gmail.com: TypeError: window._dashToDock is not a function
# Shows a typical JavaScript error from a broken extension in the journal
# The UUID identifies the extension, and the error points to the failing code
The error message names the exact extension causing the crash. Use the UUID to disable it.
Read the journal. The error message names the exact extension causing the crash.
Debug with the JavaScript Console
If an extension fails silently, the JS console catches the error. Press Alt+F2, type js, and press Enter. The console opens and logs errors from the current session. This is invaluable for developers or when an extension works but behaves oddly. The console shows errors in real-time, which is faster than digging through journalctl.
Open the console and trigger the action that causes the issue. Watch for red error messages. The console also lets you run JavaScript commands to inspect the shell state.
Use the console for live debugging. It shows errors as they happen.
When to use each method
Use the Extensions Manager app when you want a visual overview of installed extensions and need to tweak settings without opening a browser.
Use the browser connector when you are browsing extensions.gnome.org and want to install community extensions with a single click.
Use DNF packages when you want extensions managed by the system package manager for automatic updates and dependency tracking.
Use the gnome-extensions CLI when you are managing a headless server, scripting a setup, or recovering from a broken desktop session.
Use the disable-user-extensions gsettings key when GNOME Shell crashes on login and you need to regain access to a working session.
Use the JavaScript console when an extension behaves incorrectly but doesn't crash the shell.