AddonManager

Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

The AddonManager object is the global API used to access information about add-ons installed in the application and to manipulate them. The majority of the methods are asynchronous meaning that results are delivered through callbacks passed to the method. The callbacks will be called just once but that may be before or after the method returns.

One of the forces of the AddonManager is that it deals with any kind (type) of add-on in a generic manner. To do so many methods of the AddonManager take the add-on types as parameters. The existing add-on types are defined in XPIProvider.jsm and are, at this time, the following: extension, theme, locale, multipackage, dictionary and experiment.

To import the AddonManager object in the Add-on SDK, use:

const { AddonManager } = require("resource://gre/modules/AddonManager.jsm");

To import it in a normal bootstrapped extension or similar, use:

Cu.import("resource://gre/modules/AddonManager.jsm");

Method Overview

Promise? getInstallForURL(in string url, in InstallCallback? callback, in string mimetype, in string hash, in string name, in string iconURL, in string version, in nsILoadGroup loadGroup)

Promise? getInstallForFile(in nsIFile file, in InstallCallback? callback, in string mimetype)

Promise? getAllInstalls(in InstallListCallback? callback)

Promise? getInstallsByTypes(in string types[], in InstallListCallback? callback)

void installAddonsFromWebpage(in string mimetype, in nsIDOMWindow source, in nsIURI uri, in AddonInstall installs[])

void addInstallListener(in InstallListener listener)

void removeInstallListener(in InstallListener listener)

Promise? getAllAddons(in AddonListCallback? callback)

Promise? getAddonByID(in string id, in AddonCallback? callback)

Promise? getAddonBySyncGUID(in string id, in AddonCallback? callback)

Promise? getAddonsByIDs(in string ids[], in AddonListCallback? callback)

Promise? getAddonsByTypes(in string types[], in AddonListCallback? callback)

Promise? getAddonsWithOperationsByTypes(in string types[], in AddonListCallback? callback)

void addAddonListener(in AddonListener listener)

void removeAddonListener(in AddonListener listener)

void addTypeListener(in TypeListener listener)

void removeTypeListener(in TypeListener listener)

nsIURI getURIForResourceInFile(in nsIFile aFile, in string aPath)

Properties Overview

Attribute	Type	Description
`addonTypes`	`dictionary`	A dictionary that maps type ID to `AddonType`.
`autoUpdateDefault`	`boolean`	Whether add-ons should auto-update by default (overrideable per add-on). Corresponds to the `extensions.autoUpdateDefault` preference.

Callbacks

InstallCallback()

A callback that is passed a single AddonInstall

void InstallCallback(
  in AddonInstall install
)

Parameters

install: The AddonInstall passed back from the asynchronous request

InstallListCallback()

A callback that is passed an array of AddonInstalls

void InstallListCallback(
  in AddonInstall installs[]
)

Parameters

installs: The array of AddonInstalls passed back from the asynchronous request

AddonCallback()

A callback that is passed a single Addon

void AddonCallback(
  in Addon addon
)

Parameters

addon: The Addon passed back from the asynchronous request. If an error occurred (such as an add-on not being found), null is passed back instead.

AddonListCallback()

A callback that is passed an array of Addons

void AddonListCallback(
  in Addon addons[]
)

Parameters

addons: The array of Addons passed back from the asynchronous request

Constants

AddonInstall states

Constant	Description
`STATE_AVAILABLE`	An install that is waiting to be started.
`STATE_DOWNLOADING`	An install that is in the process of being downloaded.
`STATE_CHECKING`	An install that is checking for updated information.
`STATE_DOWNLOADED`	An install that has finished downloading and is ready to install.
`STATE_DOWNLOAD_FAILED`	An install that failed to download.
`STATE_INSTALLING`	An install that is in the process of being installed.
`STATE_INSTALLED`	An install that has successfully been installed.
`STATE_INSTALL_FAILED`	An install that has failed to install.
`STATE_CANCELLED`	An install that has been canceled.

AddonInstall errors

Constant	Description
`ERROR_NETWORK_FAILURE`	A network error occurred.
`ERROR_INCORRECT_HASH`	The downloaded file did not match the expected hash.
`ERROR_CORRUPT_FILE`	The file appears to be corrupt.
`ERROR_FILE_ACCESS`	There was an error accessing the filesystem.
`ERROR_SIGNEDSTATE_REQUIRED`	The addon must be signed and isn't.

Update check reasons

Constant	Description
`UPDATE_WHEN_USER_REQUESTED`	An update check performed at the explicit request of the user.
`UPDATE_WHEN_NEW_APP_DETECTED`	An update check performed when a new version of the application has been detected.
`UPDATE_WHEN_NEW_APP_INSTALLED`	An update check performed after a new version of the application has been installed.
`UPDATE_WHEN_PERIODIC_UPDATE`	An update check performed automatically in the background.
`UPDATE_WHEN_ADDON_INSTALLED`	An update check performed when a new add-on has been installed.

Update status values

Constant	Description
`UPDATE_STATUS_NO_ERROR`	No error was encountered.
`UPDATE_STATUS_TIMEOUT`	The update check timed out.
`UPDATE_STATUS_DOWNLOAD_ERROR`	There was an error while downloading the update information.
`UPDATE_STATUS_PARSE_ERROR`	The update information was malformed in some way.
`UPDATE_STATUS_UNKNOWN_FORMAT`	The update was not in any known format.
`UPDATE_STATUS_SECURITY_ERROR`	The update information was not correctly signed or there was an SSL error.

Auto update values

Constant	Description
`AUTOUPDATE_DISABLE`	Indicates that the add-on should not update automatically.
`AUTOUPDATE_DEFAULT`	Indicates that the add-on should update automatically only if that's the global default.
`AUTOUPDATE_ENABLE`	Indicates that the add-on should update automatically.

Pending operations

Constant	Description
`PENDING_NONE`	No operations are pending.
`PENDING_ENABLE`	This add-on will be enabled after the application restarts.
`PENDING_DISABLE`	This add-on will be disabled after the application restarts.
`PENDING_UNINSTALL`	This add-on will be uninstalled after the application restarts.
`PENDING_INSTALL`	This add-on will be installed after the application restarts.
`PENDING_UPGRADE`	This add-on will be upgraded after the application restarts.

Permissions

Constant	Description
`PERM_CAN_UNINSTALL`	This add-on can be uninstalled.
`PERM_CAN_ENABLE`	This add-on can be enabled.
`PERM_CAN_DISABLE`	This add-on can be disabled.
`PERM_CAN_UPGRADE`	This add-on can be upgraded.

Operations requiring restart

Constant	Description
`OP_NEEDS_RESTART_NONE`	No operations will require a restart.
`OP_NEEDS_RESTART_ENABLE`	Enabling the add-on will require a restart.
`OP_NEEDS_RESTART_DISABLE`	Disabling the add-on will require a restart.
`OP_NEEDS_RESTART_UNINSTALL`	Uninstalling the add-on will require a restart.
`OP_NEEDS_RESTART_INSTALL`	Installing the add-on will require a restart.

Installation scopes

Constant	Value	Description
`SCOPE_ALL`	15	A combination of all the installation scopes.
`SCOPE_APPLICATION`	4	This add-on is a part of the current application (Installed and owned by Firefox).
`SCOPE_PROFILE`	1	This add-on is installed in the current profile directory.
`SCOPE_SYSTEM`	8	This add-on is installed somewhere global to the system (installed for all users of the computer).
`SCOPE_USER`	2	This add-on is installed somewhere specific to the current user (all profiles of the logged-in user).

Note: The extensions.enabledScopes preference lets you configure which of these scopes are enabled; however, you can't turn off the profile scope. Starting in Firefox 8, you can also set the value of the preference extensions.autoDisabledScopes to prevent Firefox from automatically installing add-ons from the specified scopes.

AddonType viewTypes

Constant	Description
`VIEW_TYPE_LIST`	The type should be displayed in a regular list view in the UI.

AddonType flags

Constant	Description
`TYPE_UI_HIDE_EMPTY`	The type should be hidden from the UI if no add-ons of that type are currently installed.

Startup change types

These constants represent the lists of types of changes that can occur to add-ons during startup; they're used with the getStartupChanges(), addStartupChange(), and removeStartupChange() methods.

Constant	Description
`STARTUP_CHANGE_INSTALLED`	A list of add-ons that were detected as newly-installed during application startup. This doesn't include add-ons that were awaiting installation the last time the application was running.
`STARTUP_CHANGE_CHANGED`	A list of add-ons that were detected as having changed during startup. This includes an add-on being moved to a new location, changing version, or having been detected as possibly altered.
`STARTUP_CHANGE_UNINSTALLED`	A list of add-ons that were detected as having been uninstalled during startup. This doesn't include add-ons for which uninstall was pending the last time the application was running.
`STARTUP_CHANGE_DISABLED`	A list of add-ons that were detected as having become disabled during startup. This normally means the application determined that the add-on is incompatible. This doesn't include add-ons that were pending becoming disabled the last time the application was running.
`STARTUP_CHANGE_ENABLED`	A list of add-ons that were detected as having become enabled during startup. This normally means the application determined that an application change has made the add-on compatible. This doesn't include add-ons that were pending becoming enabled the last time the application was running.

Methods

addStartupChange()

Adds an add-on change from the add-on changes list. This is used to build the lists of changed add-ons reported by the getStartupChanges() method.

Note: Calling this method more than once for the same add-on will replace the last change that was recorded with the new one; an add-on can only appear once across all change types.

void addStartupChange(
  in string changeType,
  in string id
);

Parameters

changeType: The type of change that occurred for the specified add-on. This can be one of the Startup change types or a custom value defined by your own provider.
id: The add-on ID to add to the change list.

removeStartupChange()

Removes an add-on from the add-on changes list.

void addStartupChange(
  in string changeType,
  in string id
);

Parameters

changeType: The type of change to remove for the specified add-on. This can be one of the Startup change types or a custom value defined by your own provider.
id: The add-on ID to remove from the change list.

getStartupChanges()

Returns an array of add-on IDs that changed for a given startup change type.

string[] getStartupChanges(
  in string changeType
);

Parameters

changeType: The change type for which to retrieve a list of changed add-ons. This can be one of the Startup change types or a custom value defined by your own provider.

Return value

An array of add-on IDs indicating the add-ons for which the specified change type applies.

getInstallForURL()

Asynchronously gets an AddonInstall for a URL.

Promise? getInstallForURL(
  in string url,
  in InstallCallback? callback,
  in string mimetype,
  in string hash,
  in string name,
  in string iconURL,
  in string version,
  in nsILoadGroup loadGroup
)

Parameters

url: The url the add-on is located at
callback: A callback to pass the AddonInstall to
mimetype: The mimetype of the add-on
hash: An optional hash of the add-on
name: An optional placeholder name while the add-on is being downloaded
iconURL: An optional placeholder icon URL while the add-on is being downloaded
version: An optional placeholder version while the add-on is being downloaded
loadGroup: An optional nsILoadGroup to associate any network requests with

getInstallForFile()

Asynchronously gets an AddonInstall for an nsIFile.

Promise? getInstallForFile(
  in nsIFile file,
  in InstallCallback? callback,
  in string mimetype
)

Parameters

file: The nsIFile where the add-on is located
callback: A callback to pass the AddonInstall to
mimetype: An optional mimetype hint for the add-on

getAllInstalls()

Asynchronously gets all current AddonInstalls.

Promise? getAllInstalls(
  in InstallListCallback? callback
)

Parameters

callback: A callback which will be passed an array of AddonInstalls

getInstallsByTypes()

Asynchronously gets all current AddonInstalls optionally limiting to a list of types.

Promise? getInstallsByTypes(
  in string types[],
  in InstallListCallback? callback
)

Parameters

types: An optional array of types to retrieve. Each type is a string name.
callback: A callback which will be passed an array of AddonInstalls.

installAddonsFromWebpage()

Starts installation of an array of AddonInstall notifying the registered web install listener of blocked or started installs.

void installAddonsFromWebpage(
  in string mimetype,
  in nsIDOMWindow source,
  in nsIURI uri,
  in AddonInstall installs[]
)

Parameters

mimetype: The mimetype of add-ons being installed
source: The nsIDOMWindow that started the installs
uri: The nsIURI that started the installs
installs: The array of AddonInstalls to be installed

addInstallListener()

Adds a new InstallListener if the listener is not already registered.

void addInstallListener(
  in InstallListener listener
)

Parameters

listener: The InstallListener to add

removeInstallListener()

Removes an InstallListener if the listener is registered.

void removeInstallListener(
  in InstallListener listener
)

Parameters

listener: The InstallListener to remove

getAllAddons()

Asynchronously gets all installed Addons.

Promise? getAllAddons(
  in AddonListCallback? callback
)

`Parameters`

callback: A callback which will be passed an array of Addons

`getAddonByID()`

Asynchronously gets an Addon with a specific ID.

Promise? getAddonByID(
  in string id,
  in AddonCallback? callback
)

`Parameters`

id: The ID of the Addon to retrieve
callback: The callback to pass the retrieved Addon to

`getAddonBySyncGUID()`

Asynchronously gets an Addon with a specific Sync GUID.

Promise? getAddonBySyncGUID(
  in string guid,
  in AddonCallback? callback
)

`Parameters`

guid: The Sync GUID of the Addon to retrieve
callback: The callback to pass the retrieved Addon to

`getAddonsByIDs()`

Asynchronously gets an array of Addons.

Promise? getAddonsByIDs(
  in string ids[],
  in AddonListCallback? callback
)

`Parameters`

ids: The array of IDs to retrieve
callback: The callback to pass an array of Addons to

`getAddonsByTypes()`

Asynchronously gets Addons of specific types.

Promise? getAddonsByTypes(
  in string types[],
  in AddonListCallback? callback
)

`Parameters`

types: An optional array of types to retrieve. Each type is a string name
callback: The callback to pass an array of Addons to

`getAddonsWithOperationsByTypes()`

Asynchronously gets Addons that have operations waiting for an application restart to complete.

Promise? getAddonsWithOperationsByTypes(
  in string types[],
  in AddonListCallback? callback
)

`Parameters`

types: An optional array of types to retrieve. Each type is a string name.
callback: The callback to pass the array of Addons to.

`addAddonListener()`

Adds a new AddonListener if the listener is not already registered.

void addAddonListener(
  in AddonListener listener
)

`Parameters`

listener: The AddonListener to add

`removeAddonListener()`

Removes an AddonListener if the listener is registered.

void removeAddonListener(
  in AddonListener listener
)

`Parameters`

listener: The AddonListener to remove

`addTypeListener()`

Adds a new TypeListener if the listener is not already registered.

void addTypeListener(
  in TypeListener listener
)

`Parameters`

listener: The TypeListener to add

`removeTypeListener()`

Removes a TypeListener if the listener is registered.

void removeTypeListener(
  in TypeListener listener
)

`Parameters`

listener: The TypeListener to remove

`getURIForResourceInFile()`

nsIURI getURIForResourceInFile(
  in nsIFile aFile,
  in string aPath
)

`Parameters`

aFile: The nsIFile containing the resources; must be either a directory or an XPI file.
aPath: The path to find the resource at, "/" separated. If aPath is empty then the URI to the root of the contained files will be returned.

`Returns`

An nsIURI pointing at the resource.