MDN’s new design is in Beta! A sneak peek:

Preference Mechanisms

This document describes some low level details about the internals of Firefox preferences. These details are important to understand when changing preferences, either in Firefox directly or via external mechanisms like Shield.


Preferences are represented as a key/value store. Keys are dotted strings (such as browser.startup.homepage) and value are strings, integers, or booleans. Although the key of a preference implies a tree structure (homepage being a child of startup, which itself is a child of browser), this is only a convention. At a technical level the key is a simple flat string.


The preferences have two branches branches, the default branch and the user branch. Every preference logically exists in both branches, but may not have a value on a given branch.

The default branch gets its values from a file shipped with Firefox and cannot be permanently changed, except through a browser update. It can be changed during runtime, but these changes do not persist between browser restarts. Next time the browser starts the default branch will hold the original value of the preference again. The user branch is stored in a file in the profile directory, and stores any changes to preferences. For example: a user setting their homepage, or the add-on updater storing the last time it checked for updates.

Individual preferences

Getting the value of a preference follows a simple algorithm

  1. If the user branch has a value for the preference, return it.
  2. If the default branch has a value for the preference, return it.
  3. Otherwise, return null.

Preferences have the concept of "being user set". This means that the preference has a value on the user branch. This does not mean that the user took direct action, or even that the user is aware of the change. Any permanent changes to preferences are done on the user branch, so if a preference is user set, that only means that it has been changed from its original value.

Preferences do not store any historical values. Setting a value on the user branch destroys the old value. If it is important to be able to rollback to the previous user-set value, then it must be stored elsewhere. The default branch's value may be read directly, but for it to affect the browser the default branch's value must be deleted.

Document Tags and Contributors

 Contributors to this page: mythmon
 Last updated by: mythmon,