A brief guide to Mozilla preferences

This article is intended for Mozilla power users and system administrators. It provides a general overview of Mozilla preferences, including where preferences are stored, a file-by-file analysis of preference loading sequence, and information on editing preferences.

A preference is any value or defined behavior that can be set (presumably, one setting is preferable to another). Preference changes via user interface usually take effect immediately. The values are saved to the user profile (in prefs.js), for both Firefox and Thunderbird.

A preference is read from a file, and can call up to four methods: pref(), user_pref(), sticky_pref() and lockPref(). All preferences files may call pref(), user_pref() and sticky_pref(), while the config file in addition may call lockPref().

To protect privacy by preventing inadvertent loading of a preferences file in the browser, the first line of the file is made un-parseable and skipped on loading. The only exception to this is user.js .

On application launch, several preferences files are loaded. They are:

Default preference files

Firefox ships default preferences in several files, all in the application directory:

• greprefs.js - preferences shared by all applications using the Mozilla platform
• services/common/services-common.js - preferences for some shared services code, this should arguably be included in some other file
• defaults/pref/services-sync.js - default preferences for Firefox sync, also oddly misplaced
• browser/app/profile/channel-prefs.js - a file indicating the user's update channel. This is kept separate from other preferences because it can affect how updates are applied.
• browser/app/profile/firefox.js - defaults specific to Firefox
• browser/app/profile/firefox-branding.js - defaults specific to the specific kind of Firefox being installed (Nightly, Aurora, Beta, Release)
• browser/defaults/preferences/firefox-l10n.js - defaults specific to the installed language of Firefox. None of the other preference files contain locale-specific preferences.

Config. file

A configuration file, usually with .cfg extension, may be called from a default pref file via the general.config.filename preference. This file allows preference locking via the lock_pref() function. Details on the config file is beyond the scope of this document.

User pref. files

In the profile directory are two user pref files: prefs.js and user.js.  prefs.js is automatically generated by the application and should not be edited manually, whereas user.js is an optional file the user can create to override preferences initialized by other preferences files.

On application launch, the application loads preferences in the following order:

1. Load all default pref files.

2. Optionally load the config file.

3. Load user pref files, first prefs.js, then user.js .

Preference conflicts are resolved in favor of the last entry; for example, user.js takes precedence over prefs.js .

If the application encounters any error during loading of a default pref file, the application will issue a warning that a configuration file has failed to load and then quit. This allows system administrators to know quickly if there is a configuration error in the installation. If the application encounters an error when loading user pref files, the application will issue a warning but will continue running.

Usually when the user specifically commits a preference change via user interface such as the Preferences dialog, the application saves the change by overwriting prefs.js . On application exit, all user-set preferences are saved to prefs.js . This also means that preferences initially set by user.js will also be saved to prefs.js.

Do NOT edit prefs.js directly.

Note the application never changes user.js, so on launch user.js overrides conflicting preferences from the previous application session.

When prefs.js is written, it only saves user preferences which are different from the default. The exception to this is a preference read using sticky_pref() - these preference will be written whenever the preference has a user value even when it is the same as the default.

Advanced users can set named preferences via the advanced preferences editor, by typing about:config in the Location Bar. This UI is not recommended for most users. Programmatic changes to preferences can be made using the Preferences.jsm module from JS code, or the mozilla::Preferences static class methods from C++ code.

Changing defaults

A systems administrator can modify the default preferences in two ways:

1. The administrator may add an all-companyname.js preference file (install_directory/browser/defaults/preferences/all-companyname.js).  This will be parsed last during the preference loading process.

2. The administrator may alternatively put a user.js file in app_dir/defaults/profile/ ; this will put a copy of the user.js in all new profiles. This method has the advantage of resetting preferences back to administrator defaults at every start-up. Note that, because a user typically has access privilege to his or her profile directory, he or she can change the default values if he or she knows how. Another disadvantage is that existing profiles will not be affected. This method is considered user-hostile. Any use of this technique by software such as Firefox extension to override normal user preference will result in being added to the Firefox blocklist or the preferences being forcibly removed.