Developing extensions for Firefox for Android

You'll approach the coding of an extension for Firefox for Android in the same way as you would for a desktop extension; using a text editor or tool of your choice to write the code. However, when you want to test and debug your extension you need to follow a different process, this article walks you through that process.

You can also use web-ext in your extension development. If you choose to use that tool, you'll still follow the set up and debugging processes described here, but use web-ext run to execute your extension on Firefox for Android. Among the advantages of using web-ext is its lint command. web-ext lint performs a check to determine if any of the permissions, manifest keys, and web extension APIs you’re using are incompatible with Firefox for Android.

Set up your computer and Android emulator or device

You first need to complete some one-off setup tasks on your computer and Android device.

On your development computer:

  • If you want to test on your computer by running Firefox for Android in the Android emulator:
  • If you plan to test in Firefox for Android running on a device only:
    • Download and extract the standalone Android SDK Platform-Tools package to a suitable location on your computer.
    • On Windows, Mac, or Linux: Add the location into which you extracted the tools package to your operating system’s PATH environment variable.
    • Alternatively, on Mac or Linux: Link the binary to /usr/local/bin using sudo ln -s /<extract folder>/platform-tools/adb /usr/local/bin.

On your device or Android emulator:

If you are using a device:

(If you're using web-ext, you can skip this step.) On your development computer:

  • Open a command shell.
  • Run adb devices
    You should see output similar to:
    List of devices attached
    51800F220F01564 device

    Where the hex string is your device’s (or emulator’s) code. This means adb has found your device (or emulator).

Check for Firefox for Android compatibility

Before running your extension on Firefox for Android, consider using web-ext lint. Lint performs a check to determine if any of the permissions, manifest keys, and web extension APIs you’re using are incompatible with Firefox for Android. Lint relies on your extension’s manifest.json file including strict_min_version, it then reports on the  features that are not supported by the minimum version you have set.

In the lint report:

  • incompatible permissions are identified by PERMISSION_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION,
  • incompatible manifest keys are identified by KEY_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION, and
  • incompatible APIs are identified by ANDROID_INCOMPATIBLE_API

similar to this:

WebIDE showing console with messages filtered for those including 'borderify'

Lint does not report on APIs that are not implemented by Firefox or Firefox for Android.  

When setting strict_min_version, unless you’re targeting a specific version of Firefox, choose the most recent version of Firefox you expect your extension to be compatible with. For example, you can reasonably expect that most installations of Firefox for Android will be the current or previous version. So, if the current version is 66, consider setting 65 is the minimum version:

"browser_specific_settings": {
  "gecko": {
    "strict_min_version": "65.0"

Install and run your extension in Firefox for Android

In your extension, ensure that you've included an application ID using the browser_specific_settings key in the manifest.json:

"browser_specific_settings": {
  "gecko": {
    "id": ""

If you’re using web-ext, follow the Testing in Firefox for Android instructions. Otherwise, zip the content of your extension into an xpi file named to match the application ID, for example,

You now have two options for transferring and running your extension: using adb or a website.

Transfer your extension using adb

On your computer, execute /path/to/adb push /path/to/<extension file name>.xpi /mnt/sdcard/, which will transfer the extensions xpi file to your attached emulator or device.

On your Android device or in the emulator, open Firefox for Android and browse to file:///mnt/sdcard:

Firefox for Android showing the add-on xpi file located on the memory card

Tap on <extension file name>.xpi to install it. You will get a warning about the extension being blocked, tap ALLOW:

Firefox for Android blocked add-on message

An additional warning will tell you the extension is unverified, tap INSTALL:

Firefox for Android unverified add-on message

Your extension will start running (in this case a copy of the borderify example extension):

Borderify shown adding a red border to the home page

Transfer your extension via a website.

Upload your xpi file to your website and make it accessible over HTTP. Browse to the file and download it. Follow the installation instructions, which will be similar to those for an extension transferred using adb.

Debug your extension

You can debug your extension in WebIDE and view any manifest.json validation messages using adb logcat. To make use of these features, first set up Firefox remote debugging over USB or Wi-Fi.

Using WebIDE to debug your extension

Open WebIDE from the Web Developer option on the desktop Firefox menu (or with Shift + F8). Once open, select your connected device from the options in the right-hand sidebar.

Selecting the Firefox for Android device from the list in WebIDE

Now, ensure you are viewing the Main Process, then load a page in which your extension will be exercised.

Unlike desktop Firefox, where background scripts output their console messages and are debugged in the add-on debugger, while content scripts output their console messages and are debugged in the browser’s developer tools (see Debugging content scripts), you can view all messages and debug all scripts in WebIDE when running extensions in Firefox for Android.

If you included any console messages in your extension (using console.log()), you can see these the Console tab, and can use the console filter (highlighted below) to hide other console messages:

WebIDE showing console with messages filtered for those including 'borderify'

The Debugger tab then enables you to access the background script and any content scripts:

The borderify.js script in the WebIDE debugger tab

You can now apply breakpoints and observe the extension’s behavior.

Also, you can also target the document related to an extension page, for example, the background page of the borderify example, using the same approach described for the Browser Toolbox:

Selecting a specific page to examine in the WebIDE

Once you have switched to an extension page, you can inspect the extension page’s DOM elements from the Inspector panel (also the "inspect node" toggle button should work as expected) and execute WebExtension API calls from the Console panel:

Using the interactive console to test the effect of JavaScript on the open page

For more details on using WebIDE, see the WebIDE section.

Viewing manifest validation messages using the console

In addition to the console messages output through WebIDE, there may also be messages relating to the validation of the extension’s manifest.json files. These messages can be viewed using the adb logcat command. To avoid receiving other, unrelated messages, you can pipe the output through grep, filtering by the extension’s ID, for example:

/path/to/adb logcat | grep

This will give output similar to this:

I/Gecko   (30440): 1496056181889    addons.xpi    WARN    Addon with ID already installed, older version will be disabled

If your add-on fails to run, check these messages as they may provide information explaining why.

Document Tags and Contributors

Contributors to this page: rebloor, juraj, mdnwebdocs-bot, ExE-Boss, Ding-Fan, andrewtruongmoz
Last updated by: rebloor,