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.

An Addon represents an add-on that is either installed or can be installed. Instances can be created using the many getAddon methods on the AddonManager object.

The interface can represent many different kinds of add-ons and as such, some of the methods and properties are considered "required" and others "optional," which means that the optional methods or property may not exist on Addon instances for some types of add-ons. API consumers should take care to verify the existence of these methods or properties before relying on them.

Overview of required methods

void isCompatibleWith(in string appVersion, in string platformVersion)
void findUpdates(in UpdateListener listener, in integer reason, in string appVersion, in string platformVersion)

Overview of optional methods

void uninstall()
void cancelUninstall()
boolean hasResource(in string path)
nsIURI getResourceURI(in string path)
void getDataDirectory(in DataDirectoryCallback callback)

Required properties

Attribute Type Description
appDisabled Read only boolean True if this add-on cannot be used in the application based on version compatibility, dependencies, and blocklisting.
blocklistState Read only integer The current blocklist state of this add-on; see nsIBlocklistService for possible values.
creator Read only AddonAuthor The creator of the add-on.
foreignInstall Read only boolean True or false depending on whether the add-on is a third party add-on installation or not.
id Read only string The ID of the add-on. No other installed add-on will have the same ID.
isActive Read only boolean True if the add-on is currently functional. For some add-ons this will change immediately based on the appDisabled and userDisabled properties; for others it will only change after an application restart.
isCompatible Read only boolean True or false depending on whether the add-on is compatible with the current application version and platform version.
isPlatformCompatible Read only boolean True or false depending on whether the add-on is compatible with the current operating system.
name Read only string The name of the add-on.
pendingOperations Read only integer A bitfield holding all of the current operations that are waiting to be performed for this add-on. Operations are generally deferred when a restart is necessary to accomplish them.
permissions Read only integer A bitfield holding all the the operations that can be performed on this add-on. Operations my be restricted based on system policies (e.g., the system administrator may not allow certain add-ons to be uninstalled), add-on type (e.g., themes may not be disabled), or add-on state (e.g., an incompatible add-on cannot be enabled).
providesUpdatesSecurely Read only boolean True if the add-on has a secure means of updating or cannot be updated at all.
scope Read only integer Indicates what scope the add-on is installed in, per profile, user, system, or application.
type Read only string The type of the add-on.
userDisabled boolean True if the user wants this add-on to be disabled.
version Read only string The version of the add-on.

Optional properties

Attribute Type Description
aboutURL Read only string The URL of the about dialog to display for this add-on. This is passed to window.openDialog() when presenting the about dialog. If you don't provide an aboutURL, a generic about dialog is displayed. The dialog receives the Addon object representing your add-on as a parameter.
applyBackgroundUpdates integer Indicates whether updates found in the background for this add-on will be applied automatically. See auto update values. The user is provided a UI for this in the add-ons manager and it's the add-on provider's responsibility to remember its selection.
contributors Read only AddonAuthor[] An array of strings holding the contributors of the add-on.
description Read only string The description of the add-on.
developers Read only AddonAuthor[] An array of strings holding the developers of the add-on.
homepageURL Read only string The homepage URL of the add-on.
iconURL Read only string The url of the icon that represents this add-on.
install Read only AddonInstall The AddonInstall that will install this add-on. Only available if this add-on is in the process of being installed.
installDate Read only Date The Date that the add-on was first installed.
optionsURL Read only string The url of the options dialog to display for this add-on.
pendingUpgrade Read only Addon If this add-on will be replaced on the next restart, this property will hold the new Addon object.
releaseNotesURI Read only nsIURI A uri for release notes for this version.
screenshots Read only AddonScreenshot[] An array of AddonScreenshot objects containing urls of preview images for the add-on.
size Read only integer The size of the add-on's files in bytes. For an add-on that has not yet been downloaded, this may be an estimated value.
sourceURI Read only nsIURI The uri that this add-on was installed from.
syncGUID Read only string String GUID to identify the add-on in sync. The GUID is generated randomly and is made consistent across devices during sync.
translators Read only AddonAuthor[] An array of strings holding the translators of the add-on.
updateDate Read only Date The Date that the add-on was most recently updated.
operationsRequiringRestart Read only integer A bitfield holding all of the operations that will require a restart to complete for this add-on.
fullDescription Read only string  
developerComments Read only string  
eula Read only string  
icon64URL Read only string  
supportURL Read only string  
contributionURL Read only string  
contributionAmount Read only string  
averageRating Read only number  
reviewCount Read only integer  
reviewURL Read only string  
totalDownloads Read only integer  
weeklyDownloads Read only integer  
dailyUsers Read only integer  
repositoryStatus Read only integer  

Callbacks

DataDirectoryCallback()

A callback which is passed a directory path, and, when an error has occured, an Error object.

void DataDirectoryCallback(
  in string path,
  in Error error
)
Parameters
path
A string representation of the Addon's data directory.
error
If an error has occured, an Error object relevant to the error, othereise null.

Required Methods

isCompatibleWith()

Tests whether this add-on is known to be compatible with a particular application and platform version.

void isCompatibleWith(
  in string appVersion,
  in string platformVersion
)
Parameters
appVersion
An application version to test against
platformVersion
A platform version to test against

findUpdates()

Starts an update check for this add-on. This will perform asynchronously and deliver results to the given listener.

void findUpdates(
  in UpdateListener listener,
  in integer reason,
  in string appVersion,
  in string platformVersion
)
Parameters
listener
An UpdateListener for the update process
reason
A reason code for performing the update
appVersion
An application version to check for updates for
platformVersion
A platform version to check for updates for

Optional Methods

uninstall()

Uninstalls this add-on. If possible the uninstall will happen immediately, otherwise it will wait until the next application restart.

This method must be defined if an add-on has the permission PERM_CAN_UNINSTALL.

void uninstall(
)

cancelUninstall()

Cancels uninstalling an add-on if it is pending uninstall.

This method must be defined if an add-on has the pendingOperation PENDING_UNINSTALL.

void cancelUninstall(
)

hasResource()

Checks whether a file resource is available for this add-on. For XPI style add-ons, for example, it tests whether the named file was included in the package.

boolean hasResource(
  in string path
)
Parameters
path
A "/" separated path for the resource.

getResourceURI()

Gets an nsIURI to the file resource for this add-on.

nsIURI getResourceURI(
  in string path
)
Parameters
path
A "/" separated path for the resource.

getDataDirectory()

Requires Gecko 32.0(Firefox 32.0 / Thunderbird 32.0 / SeaMonkey 2.29)

Returns the path of the preferred directory, within the current profile, where an add-on should store data files. If the directory does not already exist, it will be created.

void getDataDirectory(
  in DataDirectoryCallback callback
)