How to Create a userChrome.css File

Updated October 30, 2022; Originally posted by jscher2000 on November 5, 2017.

Creating your userChrome.css file is the first step on your quest to make over Firefox's interface. It takes a couple of minutes, but it's important to take your time and get it right so Firefox loads and applies your style recipes on the first try.

At startup, Firefox will check for the userChrome.css file in a particular location: a folder named chrome inside your currently active profile folder. The profile folder is where all of your current settings and add-ons are stored. (If you want to learn more about that folder, see "Profiles — Where Firefox stores your bookmarks, passwords and other user data" on Mozilla Support.)

Here's how you set that up (full details below):

  1. Open your currently active profile folder
  2. Create a new folder named chrome
  3. Create a desktop shortcut (alias) to the chrome folder for easier future access
  4. Make sure your OS is set to show you file extensions like .txt and .css
  5. Create a new text file inside the chrome folder named userChrome.css
  6. Change a preference in Firefox so it looks for your files at startup (in Firefox 69+)

This video provides an overview; the detailed steps follow.

(1) Open your currently active profile folder

The quickest way to open the profile folder in Firefox right now is to launch it from the Troubleshooting Information page. To access that page, you can use any of these methods:

In the first table on the page, find the Profile Folder row and click the button to the right, which will say "Open Folder", "Show in Finder" or "Open Directory" on Windows, Mac or Linux, respectively. This should launch a new window with your system's file browser (e.g., Windows Explorer). You should see numerous files and folders. On Mac, if Finder shows you a semi-randomly-named folder, double-click that folder to view its contents.

Exception: If you installed Firefox from the Microsoft Windows Store, the profile folder is in an obscure location and the button mentioned above doesn't find it yet. As a starting point, you can type or paste %LOCALAPPDATA%\Packages into the Windows search box (or the File Explorer address bar) and press Enter to launch into the Packages folder. Look for an entry starting with Mozilla.Firefox and click into that folder, then LocalCache, then Roaming, then Mozilla, then Firefox, then Profiles. If you have multiple profiles, you'll need to compare the name on the Troubleshooting Information page to select the relevant one.

(2) Create a new folder named chrome

Normally, your profile does not contain a chrome folder unless you've been running Firefox for a very, very long time. To create a chrome folder, you can use the standard method provided by your file browser. For example, on Windows:

On Mac:

(3) Create a desktop shortcut (alias) to the chrome folder for easier future access

It is very likely that you will need to add or modify files to the chrome folder in the future. I recommend adding a shortcut to the folder on your desktop for easier access. To create a shortcut, you can use the standard method provided by your file browser. On Windows, right-click the chrome folder, click Send To, then click Desktop (as shortcut). On Mac, Ctrl+click / two-finger-click the chrome folder, then click Make Alias. Drag the new chrome alias item to the Desktop.

(4) Make sure your OS is set to show you file extensions like .txt and .css

Out of the box, Windows and MacOS hide certain common file extensions to reduce the appearance of clutter. However, this makes it difficult to change a file extension when you want to. Since both .txt and .css are common file extensions, we need to (at least temporarily) turn off this feature.

In newer visions of Windows, where Windows Explorer has a "ribbon" at the top with a View tab, you can click View, then find the checkbox for "File name extensions" and check the box. In older versions of Windows, one of these methods should work:

On Mac, click Finder > Preferences, then on the Advanced panel, check the box for "Show all filename extensions".

(5) Create a new text file inside the chrome folder named userChrome.css (or download a blank one)

Double-click chrome to open the chrome folder. The method you use to create the userChrome.css file may vary depending on the features provided by your file browser. Here's how you can do it in Windows: Right-click a blank area of the list, click New, then Text Document. Type userChrome.css — with only the C capitalized — in place of New Text Document.txt, then press Enter or click away to finish the edit.

For either Mac or Windows, you can use the following link to save the file into your chrome folder (or if it goes into Downloads, move it to the chrome folder): userChrome.css (blank file).

Congratulations, you're done creating the file. It's currently empty and awaiting a purpose in life. Firefox will learn about it the next time you exit out of Firefox and start it up again. (For Firefox 69, see step 6.)

Alternately, if you have some CSS code ready to paste into a userChrome.css file, you can do that using the following page and download your userChrome.css file from there: Generate Downloadable userChrome.css File.

(6) Set Firefox to look for userChrome.css at startup (updated 5/24/2019)

To make startup faster for most users, Firefox 69 will no longer look for this file automatically. You need to tell it to look. Here's how:

  1. In a new tab, type or paste about:config in the address bar and press Enter/Return. Click the button accepting the risk.
  2. In the search box above the list, type or paste userprof and pause while the list is filtered. If you do not see anything on the list, please ignore the rest of these instructions. You can close this tab now.
  3. Double-click the toolkit.legacyUserProfileCustomizations.stylesheets preference to switch the value from false to true.

That change should take effect on your next startup.

Adding Style Recipes to userChrome.css

When you're ready to add rules to the file, you may want to use a good text editor. There are suggestions for open source editors as well as information about using Firefox's Browser Toolbox, on these pages: