When the default GNOME settings fall short
You installed Fedora Workstation. The desktop looks clean, but the window controls are on the left, the cursor is too small, and the default shell theme clashes with your wallpaper. You open Settings, scroll through Appearance, and hit a wall. GNOME deliberately hides advanced toggles to keep the experience stable across hardware. You need a tool that exposes those hidden controls without breaking the session.
What GNOME Tweaks actually does
GNOME stores desktop preferences in a centralized key-value database called dconf. The Settings application only exposes a curated subset of those keys. Tweaks is just a graphical frontend that reads and writes to the same dconf database. Think of Settings as a kiosk with preset buttons, and Tweaks as the service panel behind the counter. Both control the same machine. Tweaks does not replace Settings. It supplements it.
The tool maps directly to gsettings schemas. When you toggle a switch in Tweaks, it runs a gsettings set command under the hood. When you change a font or theme, it updates the corresponding dconf path and broadcasts a desktop environment signal so active windows refresh. Understanding this backend relationship saves you from guessing why a change did not apply.
Run dconf watch / in a terminal before you touch Tweaks. Watch the paths update in real time. You will see exactly which schema keys the GUI modifies.
Installing and launching the tool
The package ships in the default Fedora repositories. You do not need third-party repos or flatpak wrappers for the core functionality.
Here is how to install the package and verify the repository state before proceeding.
sudo dnf install gnome-tweaks
# --refresh forces a metadata check so you get the latest package version
# -y skips the interactive prompt since this is a single-package install
# The package pulls in minimal dependencies and does not modify system services
Launch the application by searching for Tweaks in the Activities overview. The left sidebar groups controls by category. Appearance handles themes and fonts. Extensions manages installed add-ons. Windows controls titlebar buttons and scaling. Top Bar and Desktop manage panel visibility and workspace behavior.
Open Tweaks from the application grid. Do not run it with sudo. Desktop configuration tools run as your user account and write to ~/.config/dconf/. Running GUI tools as root breaks ownership and triggers SELinux denials.
Applying themes and navigating Wayland restrictions
Theme management requires a specific package and a clear understanding of where GNOME looks for assets. The default installation does not include extra shell themes. You must install the base theme package first.
Here is how to install the required theme package and prepare the directory structure.
sudo dnf install gnome-shell-theme
# This package provides the default Adwaita shell theme and theme loading infrastructure
# It does not install third-party themes, only the framework GNOME expects
# Run this before attempting to switch shell themes in Tweaks
GNOME searches for themes in two locations. System-wide themes live in /usr/share/themes/. User-level themes live in ~/.local/share/themes/. The /usr/share/ path ships with packages. The ~/.local/share/ path belongs to you. Always place custom themes in your home directory. Package managers will overwrite /usr/share/ during updates.
Open Tweaks and navigate to Appearance. Select a Shell theme from the dropdown. If the dropdown shows only Adwaita, your theme directory is empty or the theme structure is malformed. A valid theme requires a gnome-shell/ subdirectory containing gnome-shell.css and an index.theme file in the parent folder.
Wayland blocks custom shell themes by default. The compositor runs with elevated privileges and loading arbitrary CSS or JavaScript from themes could allow keylogging or screen capture. X11 does not enforce this restriction because the X server architecture separates client rendering from input handling. If you need a custom shell theme, switch to the X11 session at the login screen. Click your username, select the gear icon, choose GNOME on Xorg, and log in.
Log out and back in after changing shell themes. GNOME Shell caches theme assets on startup. The cache does not refresh automatically.
Managing extensions and window behavior
The Extensions tab in Tweaks shows every extension installed on your system. It provides a single toggle to enable or disable each add-on. This view is more reliable than the browser-based GNOME Extensions portal for local management. The portal handles downloads. Tweaks handles runtime state.
Here is how to check which extensions are currently active and verify their compatibility.
gnome-extensions list
# Lists all installed extensions with their UUIDs
# The output shows enabled extensions first, then disabled ones
# Use this to cross-reference with the Tweaks interface
Some extensions modify the shell UI directly. Others hook into GTK client-side decorations. Tweaks cannot fix extensions that crash the shell. If your desktop freezes after enabling an add-on, switch to a virtual terminal with Ctrl+Alt+F3, log in, and run gnome-extensions disable <uuid>. Return to the graphical session with Ctrl+Alt+F1.
The Windows tab handles scaling and titlebar layout. The Scaling Factor dropdown changes the entire desktop resolution multiplier. Use it for high-DPI displays or external monitors. The Titlebar Buttons section lets you move minimize, maximize, and close buttons to the left or right. The layout string follows a specific syntax. appmenu: adds the application menu. close: adds the close button. Separate items with colons. Do not add spaces.
Apply window scaling changes and restart your session. GTK applications cache display metrics. The change will not propagate to already-open windows.
Verifying changes and restoring broken contexts
Tweaks writes to dconf, but manual edits to GTK configuration files can bypass the database. If you edited ~/.config/gtk-3.0/settings.ini directly, the file might lose its correct SELinux context. SELinux enforces type transitions on user configuration directories. A mismatched context causes GTK to ignore the file silently.
Here is how to verify the current theme and restore the correct security context.
gsettings get org.gnome.desktop.interface gtk-theme
# Queries the dconf database directly for the active GTK theme
# Returns the exact theme name registered in the system
# Use this to confirm Tweaks actually wrote the value
restorecon -Rv ~/.config/gtk-3.0/
# -R processes the directory recursively
# -v prints each file that gets relabeled
# restorecon reads the default SELinux policy and fixes mismatched contexts
SELinux denials from configuration files show up in journalctl -t setroubleshoot. The output includes a one-line summary explaining which process was blocked and why. Read those lines before disabling SELinux. Most theme and extension issues are path or permission problems, not policy failures.
Run journalctl -xeu gnome-shell after a crash. The x flag adds explanatory text and the e flag jumps to the end. You will see the exact extension or theme file that triggered the fault.
Common pitfalls and error patterns
Theme changes do not apply immediately. GNOME Shell caches CSS and icon themes on startup. A logout cycle clears the cache. Do not restart the shell with Alt+F2 and r. That shortcut only works on X11 and is disabled on Wayland for security reasons.
Extension conflicts appear as a black screen or a frozen top bar. The error usually looks like this:
JS ERROR: TypeError: meta.is_wayland_compositor is not a function
# The extension calls an X11-only API on a Wayland session
# Wayland removed several meta functions to enforce security boundaries
# Disable the extension and update it to a Wayland-compatible version
Font rendering looks blurry or too thin. Tweaks exposes the Font Rendering tab, but the actual hinting and antialiasing values live in ~/.config/fontconfig/fonts.conf. Tweaks writes to dconf, which GTK reads. Applications that bypass GTK (like Qt or Electron) ignore dconf and read fontconfig directly. Install fontconfig configuration tools if you need system-wide font control.
Scaling artifacts appear on mixed-DPI setups. GNOME does not support per-application scaling natively. Tweaks applies a global multiplier. Use XDG_CURRENT_DESKTOP environment variables or containerized apps for per-app scaling.
Check the actual error before guessing. Half the time the symptom is a missing dependency or a cached asset.
When to use Tweaks versus alternatives
Use Tweaks when you need a graphical toggle for window controls, font rendering, or user-level themes.
Use gsettings when you are scripting desktop preferences or deploying images across multiple machines.
Use the GNOME Extensions browser portal when you need to download and install new extensions directly from the web.
Stick to the default Settings application when you only need to adjust display resolution, network profiles, or power management.
Switch to X11 when you require legacy shell themes or extensions that depend on deprecated X11 APIs.
Stay on Wayland when you want hardware acceleration, smoother input latency, and stricter security isolation.