Hack 25. Migrate Firefox Profiles

Move user data between separate Firefox installations or between separate versions.

Welcome to complexity. Every piece of software has an Achilles heel, and Firefox's is the tangle of issues that surround its user profiles. Moving profiles is tricky, and you have to be careful. Fortunately, it's a well-established problem and all that's required is excessive care. There are plans afoot to simplify all of this in a future, minor version. But for now, moving complete Firefox profiles is difficult for numerous reasons:

Use of absolute pathnames in some configuration files causes problems.
Some pathnames aren't portable across Windows, Unix, and Macintosh.
Profiles are constrained to obey operating system conventions on all platforms.
Some features were completed only recently, after protracted investigation.
There are numerous deployment variations, all of which have to be catered for.
Security requirements for salted directory names [Hack #11] make life harder.
Some information is stored outside profiles in registry files (registry.dat, mozver.dat, and the Windows Registry on Windows, registry on Unix).
Preferences customized at the platform level can affect profiles [Hack #23] .

There are at least three ways to effect a partial escape from these problems:

The Windows-only solution is to use MozBackup (http://mozbackup.jasnapaka.com/), a small backup tool that copies the web browsing state information only (history, bookmarks, etc.). It's a simple copy approach that requires new profiles at each target installation before restoring the data.
The second escape hatch is to experiment with server-oriented profile tools [Hack #28] .
The third option is to simplify matters with desalted profiles [Hack #11] .

Before proceeding to the details, here are two things to keep in mind:

Never share one profile between two separate running instances of Firefox.
The Mozilla registry (registry.dat on Windows) records the locations of all profiles.

3.5.1. Migrating Between Identical Platforms

If two computers have the same operating system version and the same users, and the users' home directories have the same paths, then the whole profile area can simply be copied from one computer to the other. Mozilla registry files must be copied as well. On the target computer, replace the local profile with the copied one. Do the same for the registry files. Since the target computer already has Firefox installed, the Windows Registry should not need updates.

Even if the two versions of the Mozilla or Firefox installs are identical, the profile might behave differently after migration. This can happen if one or both platform installs has been customized so that default preferences are not the same on both [Hack #23] . The profile will notice these different defaults at runtime but will not record them anywhere.

3.5.2. Migrating Between Mozilla Versions

Firefox can read all the profile information of any older Mozilla-based versions. Examples are beta versions of Firefox, the Mozilla Application Suite, and Netscape Versions 4.x-7.x. To read that early information, Firefox must either migrate it (a formal, one-time process undertaken at install time), import it (in the case of bookmarks and address books) or read copies of it in place. The Firefox GUI can drive all but the last option.

You can read copies in place only for browsers based on Mozilla 1.x or later. To do so, identify the name of an existing Mozilla profile (default is the default name) and the directory of the same name that is at the top of the profile data. Write down the parent directory of that directory. Hand-delete (ideally move to one side) the Mozilla registries for the old version. Install Firefox, creating new registries. Start Firefox with the Profile Manager [Hack #10] and create a new profile with the same name as the old Mozilla profile. Select Choose Folder and enter the noted folder name. The profile will forever be stored under the older Mozilla folders, but it will be usable by Firefox.

There is no way to stop a new install of Firefox from automatically migrating an existing profile when it first starts up, but forced migration leaves the original profile undamaged. You can choose the destination profile of the migration using these preferences (modifying the migration process), or hand-delete the new profile after migration (undoing the effects of migration), or both:

profile.migration_behavior   /* 0 = default = put in "Profiles" */
profile.migration_behavior   /* 1 = leave in Netscape 4.x profile */
profile.migration_behavior   /* 2 = use specified directory  */

profile.migration_directory  /* absolute path to new profile */

Since no profile exists that includes these preferences, a special hack is required. Find the all.js file in the Firefox install area, and insert the wanted options there. Use the pref() function rather than user_pref().

3.5.3. Migrating Between Different Operating System Versions

Migration between Unix versions and Unix platforms is trivial. Delete the ~/.mozilla and registry files on the new OS. Copy the old ~/.mozilla folder and registry files to the new OS. If $HOME also changes, use a parallel technique to the following procedure recommended for Windows.

Under Windows, the main migration difficulty is crossing the gap from Versions 95/98/98SE/ME/NT3/NT4 to Versions 2000/XP. The former versions use filesystem paths that are different from the ones used by the latter versions, and some hand conversion is required. On the older host, note these strings:

The full pathname of the salted directory for the profile to be migrated
The profile name

Now, migrate the preferences. Make a copy of the prefs.js file from the old profile and save it. Install Firefox on the new OS and make a profile of the same name as the old one. Close Firefox. Note the full pathname of the salted directory in the new profile. Open the old preference file and change all instances of the old salted full pathname to the new salted full pathname. Change all mail. preferences to match those in the new preference file exactly and save. Overwrite the new preference file with the modified old one.

Finally, copy all other files from the old salted directory to the new one. Start Firefox to confirm the profile has migrated correctly.

Recent versions use the shorthand notation [ProfD] to describe the path to the topmost directory. This increases portability in simple cases, but it can yield some bizarre paths on Windows if files outside the current profile's top folder are referenced:

[ProfD]../../../../some/other/file.dat

It is possible to use the one profile under two versions of Windows on a dual-boot computer (or under VMware). Boot into the Windows version where Firefox already exists. Note the path to the profile required. Reboot into the other Windows version. Install Firefox with the same profile name, and pick Choose Folder when you create the profile. Choose the folder of the profile used under the other Windows version.

3.5.4. Migrating Between Different Operating System Users

This migration operates in the same way as the last one. Care is required to get all hardcoded paths in the preference files correct. Firefox doesn't care much who the current operating system user is, except for the purposes of NTLM on Windows. When copying files from user to user, ensure that the right ownership and protections are granted.

On Windows, if you change your username and then log out and log back in as that new user, Firefox won't recover the profile of the old user and won't start up properly. To fix that, start Firefox with a profile creation option [Hack #10] . After the new profile is created, shut Firefox down and migrate the old profile to the new one [Section 3.5.1, earlier in this hack].

3.5.5. Migrating Between Windows and Linux

There is currently no simple way to achieve this end, other than to copy profile information file-by-file from Windows to Linux. In the case of the preference files, each line of those files must be checked for operating-system-specific paths and modified as required.