MDN will be in maintenance mode on Friday September 22nd, starting at 10 AM Pacific / 5 PM UTC, for about 1 hour.


Developing extensions for Firefox for Android

You will approach the coding of an extension for Firefox for Android in the same way as you would for a desktop extension using WebExtension APIs; using a text editor or tool of your choice to write the code. However, when you get to testing and debugging your extension you need to follow a different process, this article walks you through that process.

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:

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).

Install and run your extension in Firefox for Android

In your extension ensure that you have included an application ID using the applications key in the manifest.json:

 "applications": {
    "gecko": {
       "id": ""

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 Developer option on the desktop Firefox menu. 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: andrewtruongmoz, rebloor
 Last updated by: andrewtruongmoz,