Distribute Manifest V2 and V3 extensions

Firefox added support for Manifest Version 3 (MV3) extensions in Firefox 109, which was released to general availability January 17, 2023. Earlier versions of Firefox are only compatible with Manifest Version 2 (MV2) extensions.

It is not possible to create a version of an extension that is MV2- and MV3-compatible. Therefore, you need a way of distributing both types of extension if you need to continue supporting older clients, such as Firefox ESR. (Firefox ESR 102.x, the extended support release for enterprises – large companies and organizations – is supported until September 2023, when the ESR release moves to a version supporting MV3).

To help address the situation, AMO can distribute your MV2-compatible extension and sign an MV3-compatible version for self-distribution. Some developers use this as a form of a beta channel, though it is not officially supported as such.

However, if you choose to remain on MV2 and wait to transition to MV3 later, you can take steps in MV2 that move your extension closer to what is necessary for MV3. As usual, if your extension depends on features only available to recent Firefox versions, specify the compatible Firefox version in the strict_min_version field in manifest.json. Then, older Firefox extensions are not updated. A new user on an old Firefox version can install an older version of the extension using the “See all versions” link at the extension listing on AMO.

Prepare your MV3 version

To support automatic updates to newer MV3 versions, you must create and make an update manifest file available and include the file’s location in the extension’s manifest file.

See Updating your extension for details about the update manifest file format and manifest change needed.

Get a signed MV3 version

To get a signed version of your MV3 extension:

1. On AMO, when you upload the MV3 extension version, change “Where to host version” to “on your own”.

   You must change it back to “on this site” for MV2 versions, as the most recently used channel is remembered.

2. For API uploads, specify channel=unlisted for the self-distribution channel.

See Self-distribution for more details on the process.

How to distribute the MV3 version

Self-distributed versions cannot be downloaded by users directly from AMO. You must distribute the experimental XPI to users yourself, such as by a download from your website, email, etc.

See Distributing an add-on yourself for more details on the process.

Transition your experimental MV3 version to your live version

When you want to support just MV3-compatible versions of Firefox for your extension, visit AMO and upload the MV3 version to the primary AMO listed channel (“on this site”), without the update_url in the browser_specific_settings manifest key. Then, when signed, download the XPI and distribute it to your users as you did originally. The lack of the update_url manifest key means users get future updates from the AMO channel.