Extensions and the add-on ID

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

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

Firefox add-ons contain a unique identifier which is used both inside Firefox itself 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 this add-on.

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

Extensions can explicitly set the add-on ID using the browser_specific_settings key in manifest.json. However, this key is usually optional for Manifest V2 extensions. If you don't set it, then you can usually 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 will show a warning if you include it.

Note, though, that some WebExtension APIs use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs in Firefox, then you must set the ID explicitly using the browser_specific_settings key. See When do you need an Add-on ID?.

Developing and debugging

If your manifest.json does not contain an ID then the extension will be 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 will be used. If you then restart Firefox and load the add-on again, it will get a new ID.

If you turn the extension into an .xpi or .zip and install it through about:addons, it will not work. To have it work in this scenario, you will need to add in 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 will generate one for you. It's only at this point that the add-on will be assigned a permanent ID, which will be embedded in the signed packaged extension.

Updating

Even after this point, though, you don't generally have to deal with the ID at all. 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 this particular add-on, even though it doesn't contain an ID.

It's essential with this workflow that you update the add-on manually using its page on AMO, otherwise AMO will not understand that the submission is an update to an existing add-on, and will treat the update as a brand-new add-on.

What happens with Manifest V3?

All Manifest V3 extensions need an add-on ID in their manifest.json when submitted to AMO. Contrary to Manifest V2 extensions, AMO will not accept Manifest V3 extensions without an ID and it will not automatically embed this ID in the signed packaged extension.

When do you 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 an add-on ID when:

See browser_specific_settings in manifest.json for the syntax of setting the extension ID.