Distribute Manifest V2 and V3 extensions

Learn how to distribute versions of your extension supporting Manifest V2 and V3.

Firefox is adding support for Manifest Version 3 (MV3) extensions in Firefox 109, which releases to general availability January 17, 2023. However, earlier versions of Firefox are only compatible with Manifest Version 2 (MV2) extensions. And, it is not possible to create a version of an extension that is MV2 and MV3 compatible.

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.

When deciding which version is most appropriate to distribute to your users through AMO, consider that:

  • When Firefox 109 becomes available, it may take several weeks for most users to update from a version of the browser that only supports MV2.
  • Older clients, such as Firefox ESR – the extended support release for enterprises (large companies and organizations) – will remain in use for several months (Firefox ESR 102.x is supported until September 2023, when the ESR release will move to a version supporting MV3).

So, if your user base is large, or you have requirements to provide support for older Firefox versions for an extended period, we recommend you consider using this alternate distribution for your MV3 version.

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. Older Firefox extensions will not receive an update. 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 need to 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 need to 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 will get updates from the AMO channel in the future.

Take care with version numbers. The version number needs to be higher than the earlier listed MV2 and experimental MV3 versions. Firefox only upgrades the extension if the version number is greater than the installed version.