At runtime Firefox uses a settings directory, or profile, to hold all of the user-specific settings such as bookmarks, history and extensions. During startup Firefox chooses that directory based on a few criteria including command line arguments, environment variables and a file that lists known and default profiles.

Firefox 67 had the goal of allowing users to use different installs of Firefox simultaneously, without needing to configure command line arguments, and stopping the behaviour of using profiles with older versions of Firefox than they have seen since this behaviour is not supported and known to cause problems that are difficult to diagnose and fix and in some cases are serious enough to make Firefox completely unusable. To that end changes were made to profile selection.

This article describes in detail how profile selection used to work, how it now works in Firefox 67 and how we migrate users from earlier versions.

Previous behaviour

On startup Firefox would load a list of known profiles from a profiles.ini file located at a specific location in the user’s home directory. It includes a few settings and a list of the known profiles and their location on disk. One of these would be marked as the default profile. This default applies to any version or install of Firefox that the user runs.

Firefox then checks a number of environment variables and command line arguments that may override the default profile. The details are not covered here since that behaviour has not changed. Suffice to say that once these checks are done Firefox will have either chosen a profile to run with or not found one at all.

If no profile was found and there are profiles listed in profiles.ini (this would indicate either a bad command line argument or none of the profiles being marked as the default) then a profile manager is shown to allow the user to select or create a new profile to use as the default.

If no profile was found and profiles.ini is empty then this is considered to be a first run of Firefox and a new empty default profile is created and used with no user interaction.

The user is able to change the default profile at any time through the profile manager, this will change the default for all installs and versions of Firefox.

Firefox Developer Edition

One complication is Firefox Developer Edition which normally uses a different default profile from other versions of Firefox. This is achieved by ignoring the normal default profile marker in profiles.ini and instead using a profile named “dev-edition-default” as the default. This difference caused various bugs and so there was a desire to make Developer Edition behave the same as other versions.

Multiple instances

One additional detail is what happens when there is already an instance of Firefox running. Before profile selection starts Firefox attempts to find an existing instance of Firefox on the system. If one exists then instead of starting up any command line arguments are sent to the existing instance and executed there.

On Windows only one instance of Firefox can run at a time unless the -no-remote command line argument is used for additional instances. These will start regardless of other running instance but also any future Firefox start will not be able to detect these instances and so will start if no normal instance is found. When multiple instances are running each one must use a separate profile. Profile locks are used to enforce this.

On linux it is similar but with a few complexities. If a command line argument specifying a profile is passed then Firefox will only attempt to find and hand off to an existing instance using that profile, if not found it will continue to start up. Also a -new-instance argument can be passed causing Firefox to start regardless of existing instances.

New behaviour

With versions of Firefox from 67 and onwards, rather than there being a default profile for all installs of Firefox each installation of Firefox (based on the physical location on disk after following any symbolic links) has its own default profile.

During this section “old profile” refers to the profile that would have been used as the default by versions of Firefox before 67, “dedicated profile” refers to the profile marked as the default for an install of Firefox.

On startup Firefox still loads profiles.ini, it contains the same information as previously. One of the known profiles may be marked as the old default. Additionally profiles.ini now includes a list of known Firefox installs. Each new section is named based on a hash of the Firefox installation directory. Each install section includes the location on disk of the dedicated profile for that install as well as a marker for whether the profile is “locked” to that install.

As previously Firefox still checks command line arguments and environment variables which may override the default profile selection. Past that if there is already a dedicated default for this install then that is used as the default profile and start up continues.

Where the behaviour diverges is where there was no dedicated default marked for this install (this includes the case where Firefox is starting as the result of a restart and the previous run was using the old default profile, this generally occurs during an automatic restart to apply an update to a version 67 or higher).

If the install section exists in profiles.ini but did not refer to any existing profile (it has since been deleted) then a new dedicated default profile is created and used.

If no install section exists in profiles.ini then this is considered to be the first time this installation has run as version 67 or higher. In this case a heuristic is used to decide whether to create a new dedicated default profile or whether to mark the old default as the dedicated default for this install:

1. Does the old default profile contain a compatibility.ini file and can it be parsed. If not then create a new dedicated default profile and continue startup. (Only very very old versions of Firefox do not create this file, so it being missing either means this is a completely empty profile or is so old that it likely isn’t usable with modern versions of Firefox).
2. The compatibility.ini file includes information about the last install of Firefox to use the old default profile. If the old default profile was last used by a different install of Firefox then create a new dedicated default profile and continue startup.
3. Check if any other known installs of Firefox have the old default marked as their dedicated default and the profile is marked as “locked” to the install. If so create a new dedicated default profile and continue startup.
4. Mark the old default profile as the dedicated default profile for this install, remove it as the dedicated default profile for other installs of Firefox (done in such a way that when they next startup they will just create a new profile rather than attempting to use the old default). Continue startup. The profile is still marked as the old default at this point so older versions of Firefox will continue to use as their default until they are updated.
   • Later during startup (this cannot be done during early startup for various reasons) check if this install of Firefox is marked as the OS default browser. If so mark the dedicated default profile as “locked” to this install.

The user is still able to change the dedicated default profile for this install of Firefox using the profile manager, the change will only apply to this install of Firefox. Making a selection in this way will mark the chosen profile as “locked” to this install.

Firefox Developer Edition

With Firefox Developer Edition 67 default profile selection has been changed to be more standard. Developer Edition now uses the same system for selecting the dedicated default as other versions of Firefox 67 and no longer relies on specific profile naming. The only change to the above description is that “old profile” refers to the profile named “dev-edition-default” rather than the profile marked as default in profiles.ini.

Multiple instances

Running multiple instances of Firefox also changed with Firefox 67. Now Windows and Linux have identical behaviours:

During startup Firefox runs through its full profile selection to decide what profile is desired based on the command line arguments, environment variables and default profile information. Firefox then looks for any existing Firefox instance that is using the desired profile, if one exists then instead of starting up any command line arguments are passed to the found instance.

This has the benefit that you can run different installs of Firefox side-by-side with no additional command line arguments. Each will have its own default profile, starting one will use its default profile, starting another will use the other default profile. If you have Firefox beta running and Firefox Release is the OS default browser then opening a link in another application will open it in Firefox Release where previously it would have opened it in whatever Firefox happened to be open at that time.

With this feature the -no-remote and -new-instance flags are no longer needed to run different instances of Firefox at the same time, but they will not cause any error if used.

Blocking downgrades

Another change in Firefox 67 is profile downgrade detection. On startup Firefox looks at the profile to see if it was last used by a newer version of Firefox than the user is trying to start. This is known to cause many problems, sometimes obvious, sometimes less so. Firefox will now stop the user from doing this, offering them the option of creating a new profile to use instead.

Disabling the changes

The changes to profile selection can be reverted by setting the environment variable MOZ_LEGACY_PROFILES. This will not revert the changes to running multiple instances however. The downgrade blocking can be bypassed by setting the environment variable MOZ_ALLOW_DOWNGRADE or by passing the --allow-downgrade command line argument when running Firefox.