A brief guide to Mozilla preferences

  • Revision slug: Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences
  • Revision title: A brief guide to Mozilla preferences
  • Revision id: 326337
  • Created:
  • Creator: mathfreak
  • Is current revision? No
  • Comment

Revision Content

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.

Feedback and comments to bug 158384.

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

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:

*Unix-like systems used to contain a pref. file called unix.js. This file has been replaced with channel-prefs.js and vendor-gre.js.

Default pref. files

In the defaults/pref/ directory of the application installation directory are default preferences files with the .js file extension. When the application launches, 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* channel-prefs.js, vendor-gre.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.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.

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

Preferences Loading and Resolution

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 case-sensitive 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.

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

Modifying preferences

You can set user preferences via the advanced preferences editor, 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.

{{ gecko_callout_heading("8.0") }}

You can optionally include a filter query in your about:config URI when you type it, to filter which preferences you see. For example, "about:config?filter=sessionstore" will show only session storage related 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.  all.js is no longer installed by Firefox, if you create it, it will be deleted by the next app update, so use a different name.

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

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

 

Revision Source

<div class="indent">
  <p>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.</p>
  <p>Feedback and comments to bug <a class="external" href="http://bugzilla.mozilla.org/show_bug.cgi?id=158384">158384</a>.</p>
</div>
<h2 id="What_is_a_preference.3F"><span id="def">What is a preference?</span></h2>
<div class="indent">
  <p>A preference is any value or defined behavior that can be set (presumably, one setting is <q>preferable</q> to another). Preference changes via user interface usually take effect immediately. The values are saved to the user profile (in <code><a href="#files">prefs.js</a></code>), for both Firefox and Thunderbird.</p>
  <p>A preference is read from a file, and can call up to three methods: <code>pref()</code>, <code>user_pref()</code> and <code>lock_pref()</code> . All preferences files may call <code>pref()</code> and <code>user_pref()</code> , while the <span class="term">config file</span> in addition may call <code>lock_pref()</code> .</p>
</div>
<h2 id="Preferences_files"><span id="file">Preferences files</span></h2>
<div class="indent">
  <p><span id="files-skipline">To protect privacy by preventing</span> 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 <code>user.js</code> .</p>
  <p>On application launch, several preferences files are loaded. They are:</p>
  <p class="term">*Unix-like systems used to contain a pref. file called <code>unix.js</code>. This file has been replaced with <code>channel-prefs.js</code> and <code>vendor-gre.js</code>.</p>
  <dl>
    <dt class="term">
      <span id="files-def">Default <abbr title="preferences">pref.</abbr> files</span></dt>
    <dd>
      <p>In the <code>defaults/pref/</code> directory of the application installation directory are <span class="term">default preferences files</span> with the <code>.js</code> file extension. When the application launches, these files initialize preferences with default values.</p>
      <p><span id="files-def-special">The directory contains a platform-specific</span> <span class="term">default pref files</span>, whose file name depends on the platform:</p>
      <table class="table">
        <thead>
          <tr>
            <th>Platform</th>
            <th>File name</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Windows</td>
            <td><code>winpref.js</code></td>
          </tr>
          <tr>
            <td>Mac OS &amp; Mac OS X</td>
            <td><code>macprefs.js</code></td>
          </tr>
          <tr>
            <td>Unix*</td>
            <td><code>channel-prefs.js, vendor-gre.js</code></td>
          </tr>
          <tr>
            <td>Open VMS</td>
            <td><code>openvms.js</code></td>
          </tr>
          <tr>
            <td>AIX</td>
            <td><code>aix.js</code></td>
          </tr>
          <tr>
            <td>OS/2</td>
            <td><code>os2pref.js</code></td>
          </tr>
          <tr>
            <td>BeOS</td>
            <td><code>beos.js</code></td>
          </tr>
          <tr>
            <td>Photon toolkit build</td>
            <td><code>photon.js</code></td>
          </tr>
        </tbody>
      </table>
    </dd>
    <dt class="term">
      <span id="files-conf"><abbr title="configuration">Config.</abbr></span> file</dt>
    <dd>
      <p>A configuration file, usually with <code>.cfg</code> extension, may be called from a <span class="term">default pref file</span> via the <code>general.config.filename</code> preference. This file allows preference locking via the <code>lock_pref()</code> function. Details on the <span class="term">config file</span> is beyond the scope of this document.</p>
    </dd>
    <dt class="term">
      <span id="files-user">User pref. files</span></dt>
    <dd>
      <p>In the profile directory are two <span class="term">user pref files</span>: <code>prefs.js</code> and <code>user.js</code>.&nbsp; <code>prefs.js</code> is automatically generated by the application and should not be edited manually, whereas <code>user.js</code> is an optional file the user can create to override preferences initialized by other preferences files.</p>
      <p>Netscape 7 has a third <span class="term">user pref file</span> -<code>liprefs.js</code>, the roaming access preferences file.</p>
    </dd>
  </dl>
</div>
<h2 id="Preferences_Loading_and_Resolution"><span id="loading">Preferences Loading and Resolution</span></h2>
<div class="indent">
  <p>On application launch, the application loads preferences in the following order:</p>
  <ol>
    <li>
      <p>Load all <span class="term">default pref files</span>. Non-<a href="#files-def-special">platform-specific</a> <code>.js</code> files are loaded first, in reverse case-sensitive alphabetical order. Then the platform-specific file is loaded.</p>
    </li>
    <li>
      <p>Optionally load the <span class="term">config file</span>.</p>
    </li>
    <li>
      <p>Load <span class="term">user pref files</span>, first <code>prefs.js</code>, then <code>user.js</code> .</p>
    </li>
  </ol>
  <p>Preference conflicts are resolved in favor of the last entry; for example, <code>user.js</code> takes precedence over <code>prefs.js</code> .</p>
  <p>If the application encounters any error during loading of a <span class="term">default pref file</span>, 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 <span class="term">user pref files</span>, the application will issue a warning but will continue running.</p>
</div>
<h2 id="Preferences_Saving"><span id="saving">Preferences Saving</span></h2>
<div class="indent">
  <p>Usually when the user specifically commits a preference change via user interface such as the Preferences dialog, the application saves the change by overwriting <code>prefs.js</code> . On application exit, all user-set preferences are saved to <code>prefs.js</code> . This also means that preferences initially set by <code>user.js</code> will also be saved to <code>prefs.js</code>.</p>
  <p class="note"><strong>Do NOT</strong> edit <code>prefs.js</code> 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.</p>
  <p>If, for some reason, you ignore this warning and decide to edit <code>prefs.js</code>, save a copy before you make changes. Because <code>prefs.js</code> is overwritten at application exit, you must edit the file while the application is closed.</p>
  <p>Note the application never changes <code>user.js</code>, so on launch <code>user.js</code> overrides conflicting preferences from the previous application session.</p>
  <p>By default, <code>prefs.js</code> is <q>compressed</q>. When saving each preference, the application compares its value against the default loaded from <span class="term">default pref files</span> and drop the preference from <code>prefs.js</code> if they match.</p>
</div>
<h2 id="Modifying_preferences"><span id="modifying">Modifying preferences</span></h2>
<div class="indent">
  <p>You can set user preferences via the advanced preferences editor, by typing <code>about:config</code> in the Location Bar. This interface modifies the same file as the Preferences UI, <code>prefs.js</code>. Normal application users should always use this interface to modify their Preferences.</p>
  <div class="geckoVersionNote" style="undefined">
    <p>{{ gecko_callout_heading("8.0") }}</p>
    <p>You can optionally include a filter query in your about:config URI when you type it, to filter which preferences you see. For example, "about:config?filter=sessionstore" will show only session storage related preferences.</p>
  </div>
  <p>If you intend to edit preferences files manually, make sure you understand preference loading and saving as described in previous sections.</p>
  <p class="note"><strong>Do NOT</strong> edit <code>prefs.js</code> 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.</p>
  <p>If, for some reason, you ignore this warning and decide to edit <code>prefs.js</code>, save a copy before you make changes. Because <code>prefs.js</code> is overwritten at application exit, you must edit the file while the application is closed.</p>
  <p>If you want to manually change preference values for a given profile, you should do so by creating <code>user.js</code> in your profile directory. As previously noted, all values set in <code>user.js</code> take effect at program launch irrespective of changes from previous session. The file is a simple text file that looks like this:</p>
  <pre class="codeExample">
user_pref("mail.server.default.abbreviate",true); <span class="cCmt">// no newsgroup abbreviation</span>

<span class="cCmt">// use Google instead of Netscape for search</span>
user_pref("browser.search.defaulturl","http://www.google.com/");
</pre>
  <p>For your <code>user.js</code> to take effect, you must first restart your application.</p>
  <div class="note">
    <strong>Note:</strong> Preference names are case-sensitive.</div>
  <h3 id="Changing_defaults">Changing defaults</h3>
  <p>A systems administrator can modify the default preferences in two ways:</p>
  <ol>
    <li>
      <p>The administrator may edit the <code>all.js</code><sup>†</sup> <span class="term">default pref file</span> (<code>install_directory/defaults/prefs/all.js</code>). 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 <a href="#compression">compression</a>, some preferences are not saved if they match the default values, causing the profile to behave differently if used in a different installation.</p>
      <p><sup>†</sup> Because <span class="term">default pref files</span> are loaded in reverse alphabetical order, <code>all.js</code> will be loaded near the end, preventing administrator values from being overridden.&nbsp; <code>all.js</code> is no longer installed by Firefox, if you create it, it will be <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=690370" title="https://bugzilla.mozilla.org/show_bug.cgi?id=690370">deleted</a> by the next app update, so use a different name.</p>
    </li>
    <li>
      <p>The administrator may add an <code>all-<em>companyname</em>.js</code> preference file (<code>install_directory/defaults/prefs/all-<em>companyname</em>.js</code>).&nbsp; This will be parsed last during the preference loading process.</p>
    </li>
    <li>
      <p>The administrator may alternatively put a <code>user.js</code> file in <code><em>app_dir</em>/defaults/profile/</code> ; this will put a copy of the <code>user.js</code> 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.</p>
    </li>
  </ol>
  <p>Distributors can add default preference files via .XPI packages. The following is sample <code>install.js</code> code:</p>
  <pre class="codeExample">
initInstall("CustomPref", "/foo/custompref", "1.0");
addFile("custompref",           <span class="cCmt">// displayName from contents.rdf</span>
        "custompref.js",        <span class="cCmt">// source</span>
        getFolder("Defaults"),  <span class="cCmt">// target folder</span>

        "pref");                <span class="cCmt">// target subdir</span>

if (0 == getLastError())
	 performInstall();
else
	 cancelInstall();
</pre>
</div>
<p>&nbsp;</p>
Revert to this revision