Extensions and the add-on ID

Firefox add-ons contain a unique ID that is used to distinguish one add-on from any other Firefox add-on.

Firefox uses an extension's unique ID inside Firefox and on the addons.mozilla.org (AMO) website. For example, it's used by Firefox to check for updates to installed add-ons and to identify which objects (such as data stores) are controlled by the add-on.

This article describes how add-on IDs are handled for extensions built with WebExtensions APIs.

When do I need an add-on ID?

All Manifest V3 extensions need an add-on ID in their manifest.json when submitted to AMO.

For Manifest V2 extensions, you need to add an add-on ID when:

Otherwise, for Manifest V2 extensions, AMO adds an add-on ID during the signing process.

Basic workflow with no add-on ID (Manifest V2)

An add-on ID is usually optional for Manifest V2 extensions. If you don't set it, you can generally develop, debug, publish, and update your extension without ever having to deal with an ID. One advantage of this is that Google Chrome does not recognize the browser_specific_settings key and shows a warning if you include it.

However, there are some implications of not setting an add-on ID that are described in this section.

Developing and debugging

If your manifest.json does not contain an ID, the extension is assigned a randomly-generated temporary ID when you install it in Firefox through about:debugging. If you then reload the extension using the "Reload" button, the same ID is used. If you restart Firefox and load the add-on again, it gets a new ID.

If you turn the extension into an .xpi or .zip and install it through about:addons, it will not work. For it to work, you must add the browser_specific_settings key in manifest.json.

Publishing

Once you have finished developing the extension, you can package it and submit it to AMO for review and signing. If the packaged extension you upload does not contain an ID, AMO generates one. It's only at this point that the add-on is assigned a permanent ID, which is embedded in the signed packaged extension.

Updating

After publication, you don't generally have to deal with the ID. You can continue to develop the add-on without an ID, and when you want to update, upload the new version by visiting the add-on's AMO page. Because you are uploading the add-on through that page, AMO knows that this is an update to the add-on, even though it doesn't contain an ID.

With this workflow, you must update the add-on manually using its page on AMO. Otherwise, AMO does not understand that the submission is an update to an existing add-on and treats the update as a new add-on.