How Firefox's user.js Overrides prefs.js on Startup

This article explains the mechanics behind how the Mozilla Firefox web browser processes configuration files during initialization. Specifically, it details the relationship between the prefs.js and user.js files located in the user profile folder, illustrating how creating a user.js file allows users to permanently enforce custom settings by overwriting existing preferences every time the browser launches.

Understanding prefs.js

The prefs.js file is automatically generated and maintained by Firefox inside your profile folder. Whenever you change a setting in the Firefox Options menu or modify a value in the about:config page, Firefox writes that change to prefs.js.

Firefox both reads from and writes to this file. When the browser is open, changes are held in active memory and periodically saved to prefs.js, especially when the browser closes.

Understanding user.js

Unlike prefs.js, the user.js file does not exist by default. It must be manually created by the user inside the same profile directory. The purpose of user.js is to lock in specific configurations, making it useful for system administrators, privacy enthusiasts, and users who want to sync specific settings across multiple machines.

Firefox treats user.js as a read-only file. The browser will never modify, delete, or write data to user.js.

The Firefox Startup Sequence

The reason user.js overrides prefs.js comes down to the exact order in which Firefox loads configuration files into its active memory during startup:

1. Load Defaults: Firefox initializes and loads its built-in default preferences.
2. Read prefs.js: Firefox locates the profile folder, reads the prefs.js file, and applies those saved settings, overwriting the built-in defaults.
3. Read user.js: Immediately after loading prefs.js, Firefox checks the profile folder for a user.js file. If the file exists, Firefox reads it line by line.
4. Overwrite in Memory: Any preference defined in user.js is loaded into Firefox's active memory. If a setting in user.js conflicts with a setting that was just loaded from prefs.js, the user.js value wins and overwrites the prefs.js value.
5. Write Back to prefs.js: Because the user.js settings are now the active settings in Firefox's memory, Firefox will actually write these values directly into the prefs.js file when the browser saves its state or shuts down.

How the Override Persists

Because of this loading order, user.js acts as a master reset switch for the preferences it contains.

If you use user.js to set a specific homepage, and then change your homepage using the Firefox settings menu while browsing, that new change is written to prefs.js. It will remain active for your current session. However, the next time you restart Firefox, the browser will read prefs.js (your new homepage) and immediately read user.js afterward, reverting your homepage back to the one specified in user.js.

Because user.js values are copied into prefs.js during the session, simply deleting the user.js file will not revert the settings back to Firefox's defaults. The settings will remain in prefs.js until you manually change them back via the Firefox interface or about:config.