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:
user_pref(), sticky_pref() and
lockPref(). All preferences files may call
sticky_pref(), while the config file in addition may call
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
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
.cfgextension, may be called from a default pref file via the
general.config.filenamepreference. 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.jsis automatically generated by the application and should not be edited manually, whereas
user.jsis 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:
Load all default pref files.
Optionally load the config file.
Load user pref files, first
Preference conflicts are resolved in favor of the last entry; for example,
user.js takes precedence over
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
Do NOT edit
Note the application never changes
user.js, so on launch
user.js overrides conflicting preferences from the previous application session.
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.
A systems administrator can modify the default preferences in two ways:
- The administrator may add an
all-companyname.jspreference file (
install_directory/browser/defaults/preferences/all-companyname.js). This will be parsed last during the preference loading process.
The administrator may alternatively put a
app_dir/defaults/profile/; this will put a copy of the
user.jsin 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.
Note: because of abuse of user.js preferences, support for user.js may be removed in a future version of Firefox. See bug 1543752.
Sticky preferences were introduced in Firefox 40 via bug 1098343.
Sticky preferences are created when they are defined using
sticky_pref(). These preferences act as default preferences but whenever a value is created for the preference, that value is always written even when it matches the default. Sticky preferences are generally used for preferences that have a different default value in different channels with the intent being that once the user sets the preference in one channel, the preference will remain with that value when using a different channel with different defaults. For example, let's assume that Nightly has a preference "some.preference" which defaults to
true while DeveloperEdition defaults the same preference to
false and the user desires the preference to have the value
true in both channels. If the preference is not a sticky preference and the user runs DeveloperEdition and flips the pref to
true it will be saved as it is not the default. When the user then runs Nightly, the preference now has the same value as the default, so is not written by Nightly. When the user then runs DeveloperEdition again, the preference value will be
false as no user preference was written by Nightly. If the preference is defined as a sticky preference, the value
true will be written by Nightly even though it matches the current default, so when DeveloperEdition is run the preference keeps the desired value of