firefox-gnome-theme versions itself by Firefox number

The author asks distributions not to ship this theme

The warning block at the top is aimed at two different audiences and the second half is the unusual one.

Be aware that this theme might do things that are not supported by upstream
Firefox. If you face an issue while using this theme, report it here first or
test if it is reproducible in vanilla Firefox.

Then the instruction to packagers: if you are a software distribution maintainer, please do not ship these changes by default to your users unless you make it extremely clear that they are using a modified version of the Firefox interface. That is a theme author declining to be bundled, and asking for a bug to be checked against an unmodified browser first. Both halves come from someone whose change is a few thousand lines of CSS in a profile directory, where the line between styling and patching is easy to cross and easy for a user to forget.

Releases are tagged with the Firefox number they match

The versioning scheme is the browser's, not the project's.

The `master` branch of this repo supports the current Firefox stable release `157`.

Older Firefox releases are preserved as tags named after the version they support, and two further branches exist for fixes that apply only to the current beta and nightly builds. The tag list follows: v149 in March 2026, v149.1 the next day, and v157 in October, so the Firefox major version the theme tracks moved eight versions in about six months, and the patch component on a theme tag is a theme revision. There is even a one-liner that works the right tag out of the installed browser, cutting the version string down to its major number and checking that out. It is a coherent scheme, and it means a tag number and a theme version number are not the same thing.

Six install routes, and one of them touches every profile

The page lists six ways in, and the difference between them is a difference in blast radius. An application on Flathub is called the friendliest option. A single command fetches a script over HTTPS and pipes it into a shell, with its own warning above it about being careful when running scripts from the internet, and that route deliberately downloads the latest *released* version rather than the default branch.

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

The auto-install script looks for Firefox profiles in various known locations, including the home directory, Flatpak and Snap, and installs into each one it finds. The manual script touches only the default profile folder and takes flags to narrow it. There is an Arch package, and an eleven step manual procedure. So one command applies the theme to every profile on the machine, including a work profile, which is convenient and is the thing to know before running it.

Installing also symlinks a preferences file into the profile root

The theme does more than add stylesheets, and the manual route spells out the extra step.

ln -fs chrome/firefox-gnome-theme/configuration/user.js user.js

A file called `user.js` in a Firefox profile is applied on every startup and overrides what you set by hand in the configuration page. So installing the theme is not only a matter of CSS: it also points your profile at a file the theme maintains, which means the theme's preferences follow the theme across updates. That is how the two required settings get applied, and it is why the uninstall section has to tell you to go and edit that file afterwards. Two of those settings are mandatory rather than cosmetic, and the page says what breaks without each.

Two preferences are required, and one of them is named legacy

One of the two is the switch that lets a profile load custom stylesheets at all.

`toolkit.legacyUserProfileCustomizations.stylesheets`

Without it, the page says, the theme would not work. The second is required to recolour icons, and without it you get black icons everywhere. That second one is worth pausing on: it is what allows CSS to read rendering context properties, and the theme needs it on to restyle its own icons. Note the name of the first, which carries the word legacy, so the theme depends on a preference whose own name signals that it exists for compatibility with older setups. The page points at the theme's configuration file for the rest of the settings, describing them as non-essential.

The manual route rewrites line one of both your stylesheets

Here is the whole of the mutation.

sed -i '1s/^/@import "firefox-gnome-theme\/userChrome.css";\n/' userChrome.css

The same line is applied to the content stylesheet with the other filename. It replaces line one of a file inside your Firefox profile, in place, with no backup, and the page explains the constraint it is working around: every import has to come before any existing namespace declaration. There is a related detail two steps earlier that gives the game away. Both files are created empty if they do not already exist, by a shell test that appends a newline, and the stated reason is that at least one line is needed for that substitution command. So the manual install is a two-file in-place edit whose success depends on a workaround for a stream editor, and the theme's own manual path is the only one of the six that touches your stylesheets directly.

Uninstall describes an append that one install path never did

The uninstall section is three steps, and the second one is a judgement call.

Remove the unwanted preferences from your `user.js` inside your profile folder.

The following sentence explains that the install script *appends* the needed preferences to that file, and that you can find out which ones by checking the theme's configuration file. But the manual procedure symlinked the file rather than appending to it, and the two other script routes are described as installing the theme into each profile. So the advice on removal is written for the appending behaviour, and a user who followed the manual steps has a symlink to delete instead of a list to work through. The first step, removing the cloned folder, and the page's final instruction to restart, are correct either way.

The last install step is buried in a collapsed block

The manual procedure has eleven numbered steps and the eleventh is the one that makes the theme look right.

Open Firefox customization panel and move the new tab button to headerbar.

So after cloning, creating a directory, seeding two files, running two substitutions, symlinking a preferences file and restarting, the interface still has a leftover button in the wrong place until you drag it somewhere. That step lives inside a collapsed section, which is a reasonable place for it and an unlucky one for anyone who works through the list and stops. Elsewhere the page is more systematic: optional features are enabled as boolean preferences you add by hand, under a namespace of the theme's own, and the first of them hides the tab bar when only one tab is open. The tree holds two root stylesheets, a theme directory, a configuration directory, a scripts directory and two images, and there is no continuous integration or test configuration in it.

Editorial conclusion

firefox-gnome-theme is worth trying if you want Firefox to match your desktop and you are comfortable editing files inside a profile directory, because the install scripts handle the Flatpak and Snap layouts that most guides skip. Two things to know before you run one. Installing also drops a preferences file into your profile root, which Firefox applies at every start, so the theme owns some of your settings as well as your styling. And the manual route rewrites the first line of both your stylesheets in place with no backup, so read those two commands before you type them.

Frequently asked questions

Official sources

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