Firefox GNOME Theme: Make Firefox Follow Your GTK Theme with userChrome.css

What firefox-gnome-theme actually fixes

Firefox ships with its own visual language: a tab strip with its own proportions, its own button shapes, its own idea of what a toolbar looks like. On a GNOME desktop, every other window is drawn by GTK and follows Adwaita. Firefox sits next to those windows and does not match them. The README describes the project plainly as "a bunch of CSS code to make Firefox look closer to GNOME's native apps", and that is the whole scope. There is no binary, no extension, no daemon. The repository is mostly CSS, plus shell scripts that copy it into the right place.

The audience is narrow and specific: Linux users on GNOME who already know what a Firefox profile directory is, and who are willing to make Firefox look like it belongs on their desktop. If you use Firefox on Windows or macOS, or you run a different desktop environment, the Adwaita assumptions in the CSS have nothing to attach to. The project does not pretend otherwise. The README opens with a warning that the theme "might do things that are not supported by upstream Firefox", and asks distribution maintainers not to ship it by default unless they make clear that users are running a modified Firefox UI.

How the CSS reaches Firefox: userChrome.css, userContent.css and user.js

Firefox will not load arbitrary CSS from a profile unless a preference allows it. The theme relies on two files that Firefox reads at startup, userChrome.css for the browser chrome (tabs, toolbars, menus, the window frame) and userContent.css for internal pages. Both live in a chrome directory inside the profile. The theme itself is cloned into a subdirectory of chrome, and the profile's two CSS files import it.

The import order matters. The manual instructions state that all @import rules must come before any existing @namespace declarations, which is why the install steps prepend the import lines with sed rather than appending them. A second file, configuration/user.js, carries the preferences. The README names two as required: toolkit.legacyUserProfileCustomizations.stylesheets, without which the custom CSS is not loaded at all, and svg.context-properties.content.enabled, without which icon recoloring fails and you get black icons everywhere. The scripts symlink user.js into the profile root. Other preferences in that file are described as non essential.

The data flow is therefore: Firefox starts, reads user.js, sees that legacy profile customizations are enabled, loads userChrome.css and userContent.css, those files import the theme's CSS, and the theme's selectors override Firefox's internal styling. Everything is client-side and local. Nothing is fetched at runtime.

Installing firefox-gnome-theme and getting a first working window

The friendliest route the README offers is the Add Water app, available on Flathub as dev.qwery.AddWater. If you prefer a terminal, the project publishes a one-line installer. The README also warns, in its own words, to always be careful when running scripts from the Internet, which is fair advice for a pipe-to-shell command.

curl -s -o- https://raw.githubusercontent.com/rafaelmardojai/firefox-gnome-theme/master/scripts/install-by-curl.sh | bash

That script downloads the latest released version of the theme, not the master branch, and runs the auto-install script against it. If you want a specific branch or tag instead, clone the repository and choose one before installing.

git clone https://github.com/rafaelmardojai/firefox-gnome-theme.git
cd firefox-gnome-theme
git checkout beta

Two install scripts exist. auto-install.sh searches known Firefox profile locations, including the regular path, Flatpak and Snap, and installs into each one it finds. install.sh only touches profiles under ~/.mozilla/firefox/ unless you point it elsewhere with -f, and -p restricts it to a single profile.

./scripts/auto-install.sh
./scripts/install.sh -p pc8577yz.default-release
./scripts/install.sh -f ~/.var/app/org.mozilla.firefox/.mozilla/firefox

After the script runs, restart Firefox. The README's manual checklist ends with one step that the scripts cannot do for you: open the customization panel and move the new tab button to the headerbar. The layout assumes it is there. Arch users have a separate path: install the AUR package firefox-gnome-theme and follow the instructions at /usr/share/doc/firefox-gnome-theme/INSTALL.md.

If you install by hand, the sequence is: open about:support, find Application Basics > Profile Directory > Open Directory, open that directory in a terminal, create chrome if missing, clone the theme into it, make sure userChrome.css and userContent.css exist and are non-empty, prepend the two @import lines, symlink configuration/user.js to the profile root, and restart. The README notes that at least one line must be present in each CSS file for sed to work, hence the echo commands that create them.

Version matching is the real maintenance burden

The master branch supports the current Firefox stable release, which the README states is 150. Older Firefox releases are handled through git tags, and beta and nightly builds get their own branches for fixes that only apply there. This is the structural weakness of any userChrome theme: Firefox's internal element names and layout are not a public API, so a browser update can invalidate selectors that worked the day before.

The README provides a shortcut for picking the tag that matches your installed Firefox:

git checkout v$(firefox --version | cut -d ' ' -f 3 | cut -d '.' -f 1) # Using Firefox version

That command derives the major version from firefox --version and checks out the corresponding tag. It only works if a tag for that major version exists. The recent releases listed in the repository (v149.1, v149, v143) show the tagging cadence is tied to Firefox releases, not to a fixed schedule, so there can be a gap between a Firefox release and a matching theme tag. Updating, per the README, means following the installation steps again.

Uninstalling is documented and simple: open the profile folder, remove the chrome directory, and remove the unwanted preferences from user.js. The README notes that the install script appends the needed preferences, which is worth remembering because a leftover user.js will keep enabling custom stylesheets after the theme is gone.

Where firefox-gnome-theme is the wrong choice

The clearest failure mode is version drift. If your Firefox updates before the theme catches up, selectors stop matching and you get a partially styled window: some elements Adwaita-like, others reverting to Firefox defaults. Nothing crashes, but the result can look worse than stock Firefox. The beta and nightly branches exist precisely because those channels move faster than stable.

The second limitation is the disclaimer itself. The README states the theme might do things upstream Firefox does not support, and asks users who hit an issue to report it in the theme's tracker first or to test whether it reproduces in vanilla Firefox. That is an honest boundary: you are running a modified UI, and bug reports that turn out to be theme artifacts waste upstream maintainers' time.

Third, the project is not portable. The related searches around a Windows version have no answer in the repository, because the styling targets GNOME Adwaita and GTK. On Windows or macOS there is no GTK to match, and the theme's premise disappears. Distribution maintainers are explicitly asked not to enable it by default, so if you are packaging Firefox for others, this is not something you switch on silently.

Alternatives and how they differ in approach

The closest alternative named in the related searches is a Firefox Acrylic theme, which targets Windows rather than GNOME. That is a different platform and a different visual reference, so it is not a substitute on a GNOME desktop; it is what you would reach for if you were on Windows and wanted translucency there.

A more meaningful contrast is with GTK theme engines and GNOME extensions. Those change how GTK applications are drawn, and Firefox only follows them to the extent that Firefox itself reads GTK settings. The README's related search about making Firefox follow the GTK theme points at exactly this gap: Firefox does not fully inherit a GTK theme on its own. firefox-gnome-theme fills that gap by overriding Firefox's internal CSS directly, which is more invasive but also more complete. The trade-off is maintenance: a GTK theme does not break when Firefox ships a new release, while a userChrome theme can.

There is also the option of doing nothing and accepting Firefox's default look, or writing your own userChrome.css. The theme is essentially a curated, versioned collection of such rules, plus the install plumbing and the required preferences. If you only want one or two changes, a few lines in your own userChrome.css will not break on every Firefox release the way a large stylesheet can.

Licence, cost and what upgrading involves

The repository is released under the Unlicense, which the LICENSE file in the repository root carries. That is a public-domain-style dedication rather than a copyleft licence, so there is no obligation to publish modifications and no compatibility puzzle with other licences. This is a factual note about what the repository states, not legal advice; if licence terms matter to your distribution or product, read the LICENSE file yourself.

Cost is time, not money. The project accepts donations through PayPal and Liberapay, and there is a Matrix room at #firefox-gnome-theme:matrix.org for contact. Upgrading means re-running the install steps, which re-clones or re-checks-out the theme and reapplies the CSS imports. The README does not document an in-place upgrade command, so the practical procedure is the same as installation. Because the theme is a git checkout, you can pin a tag and stay there, but a Firefox major update will eventually leave that tag behind. The realistic maintenance pattern for a GNOME user is to check the repository after each Firefox major release and move to the matching tag or branch.

Editorial conclusion

Adopt it if you run Firefox on a GNOME desktop, you are comfortable editing userChrome.css and user.js, and you accept that a Firefox update can break the styling until the matching tag or branch catches up. Skip it on Windows and macOS, on locked-down or managed Firefox builds, or if you cannot tolerate a modified UI that upstream Firefox does not support. Verify first that your Firefox release matches the theme version the README documents, that toolkit.legacyUserProfileCustomizations.stylesheets and svg.context-properties.content.enabled are set in about:config, and that you can restore your profile by removing the chrome folder and the appended preferences.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. rafaelmardojai/firefox-gnome-theme on GitHub
4. README
5. Releases