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.

What is a preference?

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().

Preferences files

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.jsprefs.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.

Preferences Loading and Resolution

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.

Preferences Saving

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.

Modifying preferences

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.

Note: because of abuse of user.js preferences, support for user.js may be removed in a future version of Firefox.

Sticky Preferences

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 true.

Document Tags and Contributors

Tags: 
 Last updated by: Markh,