fxcss

Getting started

You need Python 3.9+ and an installed Firefox on macOS, Windows or Linux. Install fxcss, then try a theme in a disposable profile:

pipx install fxcss
fxcss try AdamXweb/WhiteSurFirefoxThemeMacOS

Close the preview window when you are done; your everyday Firefox profile is unchanged. See installation options if you do not have pipx.

Choose what you want to do next:

I want to…	Next step
Use a theme in my everyday browser	Install it, then check updates, change options or roll back.
Create or edit a theme	Start a theme, see edits live and inspect Firefox's interface.
Maintain a theme on GitHub	Generate workflows for PR previews and scheduled Firefox checks.

For local development and testing, run commands from the theme's root (the folder containing chrome/), or pass --theme /path/to/theme. Use fxcss <command> --help for its options.

https://github.com/user-attachments/assets/83dc3c67-6cad-432a-b841-d602a135a396

Explore the toolkit

Section	What you can do
Using and managing themes	Preview, install, adopt, update, roll back and remove themes; see what is installed in each profile.
Building and inspecting themes	Start a theme, reload CSS live and find the selectors and rules behind the UI.
Testing appearance	Run saved project checks, capture browser states and review visual differences.
Tracking Firefox compatibility	Save structural snapshots, compare Firefox builds and audit theme breakage.
GitHub Actions workflows	Automate PR previews, Firefox checks and screenshot publishing.
Documenting and showcasing themes	Explain install options with images and generate a visual UI reference.
Troubleshooting and configuration	Diagnose setup problems, choose installation options and understand capture limits.
Commands	Jump directly to any command.

Previewing, editing and browser testing use disposable profiles. The theme management commands install, adopt, upgrade, rollback and uninstall work on a selected real profile; profiles only reads it.

Using and managing themes

Start with a preview, then install into the profile you choose. fxcss records what it installs, checks for local edits before upgrades and keeps backups when replacing an existing theme. Already have a manually installed theme? Use adopt to bring it under management.

Looking for a theme? Browse the Firefox CSS Store or r/FirefoxCSS, then pass its GitHub repository to fxcss try.

fxcss try

fxcss try adamXweb/WhiteSurFirefoxThemeMacOS
fxcss try github.com/owner/theme --with compact-tabs
fxcss try owner/theme --info            # report what's there, launch nothing
fxcss try ~/src/my-theme                # a theme folder on this computer

Test-drive a theme before committing to it. Downloads it, installs it into a throwaway profile, and opens Firefox so you can actually use it. Your own profile is never touched — close the window and nothing remains.

It reports what it found before doing anything:

  fxcss try  AdamXweb/WhiteSurFirefoxThemeMacOS

  AdamXweb/WhiteSurFirefoxThemeMacOS  ★619  MIT
    MacOS Big Sur like theme for Firefox on MacOS & Windows. Make your Firefox look like Safari.
    latest release   v2.1.0  (2026-10-28)
    latest commit    68f8699  (2026-11-10)  fix: align the toolbar and close the tab bar gap …

  fetching release v2.1.0 …

  layout      chrome/ at the repository root  72 stylesheets, 377 KB
  loads       35 stylesheets  29 browser-window, 2 web-content, 4 shared
  user hook   customChrome.css  not shipped, as intended
  installer   install.sh  fxcss copies the files itself and never runs it

  Optional stylesheets  30 · layer any on with --with name,name
    Tweaks
    compact-tabs    hideextension   increase-contrast   singletabhidden   tabs-swapclose
    enabletabview   highlight-tab   noidentity          standard-urlbar   windows-swapclose

    Colour schemes · pick one
    theme-ayu-mirage             theme-github-dark          theme-nord
    theme-catppuccin-frappe      theme-gruvbox-dark         theme-one-dark
    …

  Setup beyond the files  1 automatic · 3 to check
    ✓ automatic  3 prefs in configuration/user.js  in fxcss's own block
    ! check      Firefox's native vertical tabs
                 a setting in Firefox's own sidebar options
    …

  README install flags  as the README words them, for its own script; fxcss never runs it
    -c  Left hand side tab close button          -v         Re-enables the tabview button
    -p  Makes tabs height compact like…          -t <name>  Colour theme (see Colour themes below)
    …

Releases are preferred over branch tips, since that is what the author blessed; --commit takes the latest commit instead, and --ref takes any tag, branch or SHA. A browser URL for a branch or folder (https://github.com/owner/theme/tree/photon-style/themes/one) is read as meaning that branch and that folder, and the branch is then tracked rather than pinned. --with name,name layers on the theme's optional stylesheets so you can see a variant without hunting through install flags. --shot dir captures the standard screenshots instead of opening a window, and --keep dir leaves the download behind so you can start editing it with watch.

How the theme is found

Theme repositories are laid out in more ways than chrome/userChrome.css. try, install and upgrade share one plan for reading a source tree, and say which layout they found:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗