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.

Preference sharing via profile sharing is not discussed here (see the profile sharing page).

Feedback and comments to bug 158384.

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 are saved to the user profile (in prefs.js). (Firefox confirmed).

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

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 pref. files

In the defaults/pref/ directory of the application install directory are default preferences files with .js file extension. On application launch these files initialize preferences with default values.

The directory contains a platform-specific default pref files, whose file name depends on the platform:

Platform	File name
Windows	winpref.js
Mac OS & Mac OS X	macprefs.js
Unix	unix.js
Open VMS	openvms.js
AIX	aix.js
OS/2	os2pref.js
BeOS	beos.js
Photon toolkit build	photon.js

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.

Netscape 7 has a third user pref file -liprefs.js, the roaming access preferences file.

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

1. Load all default pref files. Non-platform-specific .js files are loaded first, in reverse alphabetical order. Then the platform-specific file is loaded.

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, unless you really know what you are doing, because the file has a variety of editing restrictions and complicated behaviors, which are beyond the scope of this document.

If, for some reason, you ignore this warning and decide to edit prefs.js, save a copy before you make changes. Because prefs.js is overwritten at application exit, you must edit the file while the application is closed.

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

By default, prefs.js is compressed. When saving each preference, the application compares its value against the default loaded from default pref files and drop the preference from prefs.js if they match.

You can set user preferences via the advanced preferences editor, accessible by typing about:config in the Location Bar. This interface modifies the same file as the Preferences UI,prefs.js. Normal application users should always use this interface to modify their Preferences.

If you intend to edit preferences files manually, make sure you understand preference loading and saving as described in previous sections.

Do NOT edit prefs.js directly, unless you really know what you are doing, because the file has a variety of editing restrictions and complicated behaviors, which are beyond the scope of this document.

If, for some reason, you ignore this warning and decide to edit prefs.js, save a copy before you make changes. Because prefs.js is overwritten at application exit, you must edit the file while the application is closed.

If you want to manually change preference values for a given profile, you should do so by creating user.js in your profile directory. As previously noted, all values set in user.js take effect at program launch irrespective of changes from previous session. The file is a simple text file that looks like this:

user_pref("mail.server.default.abbreviate",true); // no newsgroup abbreviation

// use Google instead of Netscape for search
user_pref("browser.search.defaulturl","http://www.google.com/");

For your user.js to take effect, you must first restart your application.

Note preference names are case-sensitive.

Changing defaults

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

1. The administrator may edit the all.js^† default pref file (install_directory/defaults/prefs/all.js). This has the advantage of changing the default value for both new and existing profiles. However, note preferences set in the profile will override the default settings. Also, note due to preferences file compression, some preferences are not saved if they match the default values, causing the profile to behave differently if used in a different installation.

   ^† Because default pref files are loaded in reverse alphabetical order, all.js will be loaded near the end, preventing administrator values from being overridden.

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.

Distributors can add default preference files via .XPI packages. The following is sample install.js code:

initInstall("CustomPref", "/foo/custompref", "1.0");
addFile("custompref",           // displayName from contents.rdf
        "custompref.js",        // source
        getFolder("Defaults"),  // target folder
        "pref");                // target subdir

if (0 == getLastError())
	 performInstall();
else
	 cancelInstall();