Backup & restore of Firefox app data

This tutorial explains how one can create and restore a backup of the full Android app data, fully offline.

While the Firefox app itself does not support adb backup due to allowBackups="false" (bug 1808763), we can still access all data by connecting through a Firefox-specific debugger.

Repository: https://github.com/Rob--W/firefox-android-backup-restore

Requirements

All you need is adb, and a desktop Firefox instance to use about:debugging:

• Tutorial with screenshots of using about:debugging: https://extensionworkshop.com/documentation/develop/developing-extensions-for-firefox-for-android/#debug-your-extension
• Documentation of about:debugging: https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#connecting-to-a-remote-device
• Optional, adb over Wi-Fi (instead of USB): https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#about-colon-debugging-connecting-to-android-over-wi-fi

Relevant files

The data of Android apps are usually stored in internal storage, private to the app, inaccessible to other apps and adb. External storage at /sdcard/ can be accessed through adb, but we need to use a special subdirectory to make sure that the app can access it without requiring special storage permissions.

Examples of paths for Firefox (app ID org.mozilla.firefox):

• Private app data: /data/user/0/org.mozilla.firefox/
• Public directory: /sdcard/Android/data/org.mozilla.firefox/

The private app data directory contains several directories and files, the most important ones being:

• shared_prefs/ - Firefox UI settings and customizations.
• files/ - Firefox profile directory, with website data (cookies etc).
• databases/ - Tabs, collections, autofill, logins & passwords, and more.

The following are also relevant for consistency, but not critical:

• cache/ - Caches, including thumbnails and favicons.
• nimbus_data/ - Feature flags. Optional, but can change behavior.
• no_backup/ - Includes androidx.work database, e.g. add-on update checks.
• glean_data/ - Telemetry data (very old profiles may also have telemetry/).

Backup

To backup, prepare to receive the backup data in the terminal:

adb reverse tcp:12101 tcp:12101
nc -l -s 127.0.0.1 -p 12101 > firefox-android-backup.tar.gz

Tip

on Windows:

adb reverse tcp:12101 tcp:12101
powershell ./ncat 12101 firefox-android-backup.tar.gz

Open the Firefox app on your phone, and visit about:blank (any webpage works). Copy the contents of snippets_for_firefox_debugging.js. Open about:debugging, scroll down to "Main Process" and click on Inspect. Switch to the Console, paste the code and run it. Then type and run:

fab_backup_create();

Tip

Alternatively, you can also compress the whole archive on the device first and then send the entire file:

fab_backup_create({tempfile: true});

This will cause the device to do some work before a TCP connection happens. I feel this improves overall speed.

---

You can go one step further and also send the file size of the archive:

fab_backup_create({tempfile: true, send_size: true});

This must be used in combination with:

powershell ./ncat 12101 firefox-android-backup.tar.gz -ExpectFileSize

to get fancy download progress like "time left: X seconds".

This copies relevant files to firefox-android-backup.tar.gz without changing any data, except for one log file (and the tempfile, if tempfile: true). To remove the log/temp file, run:

fab_cleanup();

Restore

The steps below will replace relevant files with the backup.

To restore the profile from the backup, put the backup archive on the device:

adb shell mkdir /sdcard/Android/data/org.mozilla.firefox/
adb push firefox-android-backup.tar.gz /sdcard/Android/data/org.mozilla.firefox/

Open the Firefox app on your phone, and visit about:blank (any webpage works). Copy the contents of snippets_for_firefox_debugging.js. Open about:debugging, scroll down to "Main Process" and click on Inspect. Switch to the Console, paste the code and run it.

Then type fab_backup_restore(); and run it. This has no visible output, unless an error occurs. Upon successful completion, the app is killed to prevent the old app instance from corrupting the restored data. The logs can be viewed with:

adb shell cat /sdcard/Android/data/org.mozilla.firefox/firefox-android-backup.log

When you are done, remove the archive and log file with:

fab_cleanup();

Import to desktop Firefox instance

Bookmarks and Tabs (Sessions) stored in firefox-android-backup.tar.gz can be converted to a bookmarks.html file, which can then be imported on any desktop Firefox instance. You need Python 3 for this. Tested on Python 3.12.0.

Warning

Right now, the script will ignore any folders, so Bookmarks will be generated as a flat list and not be structured correctly. Possibly other bugs.

Extract the appdata folder from firefox-android-backup.tar.gz. You can use 7-Zip on Windows. If using the GUI, you need to extract it two times.

7z x firefox-android-backup.tar.gz -so | 7z x -si -ttar -ofirefox-android-backup

Run the python script and pass the path of the extracted folder as argument:

python create_bookmarks_html.py firefox-android-backup/

If things work out, you should end up with a bookmarks.html file. In Firefox, press Ctrl+Shift+O, choose Import bookmarks from HTML and select the file.