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.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
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 WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
By the end of 2017 WebExtensions will be the only supported add-on type in Firefox. To learn how to install a WebExtension for testing purposes, see Temporary Installation in Firefox. To learn how to package a WebExtension for distribution, see Publishing your WebExtension.
Extensions are packaged in a form of Installable Bundle which can be downloaded and installed by a user, or provided pre-packaged with an application or by an external program. Extensions use a directory structure which can provide chrome, components, and other files to extend the functionality of an XUL program.
Every extension must provide an install.rdf file, which contains metadata about the extension, such as its unique ID, version, author, and compatibility information.
After the extension files and install.rdf have been prepared, there are several ways to prepare an extension for installation: ZIP the extension directory into a user-installable XPI (xpinstall) file, unpack the extension directly into the user's application or profile directory, or register the extension in the Windows registry.
Note: Starting in Gecko 2.0, XPI files are no longer unpacked when extensions are installed. Instead, the XPI itself is placed in the extensions directory, and files are loaded directly out of the package. See Updating extensions for Firefox 4 for details.
Making an extension XPI
An XPI (XPInstall) file is simply a ZIP file, containing the extension files, with the install.rdf file at the root of the ZIP. Users can download XPI files from a website, or from a local file, and install by opening it, or dragging it into the Extension Manager window. The XPI file must contain only uncompressed files, or files compressed using the deflate algorithm.
The MIME type recognized by Firefox for XPI files is application/x-xpinstall. Since most HTTP servers are not configured to return this MIME type for the .xpi extension by default, you will probably need to configure your HTTP server. In the Apache HTTP Server, this can be done by adding the following directive to the configuration file or .htaccess:
AddType application/x-xpinstall .xpi
A great way to distribute XPI files intended for public dissemination is using the addons.mozilla.org web site (AMO). See Submitting an add-on to AMO for details.
Install extension files directly
If you know the location of the application (if you are installing an extension as part of the application installer, for example), you can install the extension files directly to <appdir>/extensions/<extensionID>. The extension will be found automatically by the extension manager the next time the application is launched.
When using this method you must verify that the file system permissions for the directories, and files for the extension, are set properly. Otherwise, the Extension Manager may not function properly with the extension, or the extension itself may not work properly.
Including add-ons in a customized application
A customized application can include add-ons, including extensions and themes, by placing the unpacked (that is, not the XPI files, but the packages' contents) in the <appdir>/distribution/extensions directory. This directory containing the add-on must be named the same as the ID of the add-on or theme. Add-ons packaged in this way will not be visible to the user.
Register an extension location using the Windows Registry
External installers, such as the Java runtime, may wish to install application integration points as an extension, even if the application is not yet installed. This can be accomplished on Windows using the registry.
Multi-item extension XPIs
In some cases, a single XPI file may wish to install multiple extensions/themes. A special kind of extension XPI, called the Multiple Item Package, explains how to create this kind of package. (Firefox 1.5/XULRunner 1.8 required.)
From the release of Firefox 53, multiple item extension packages are no longer supported and will not load. As a consequence, these packages are no longer accepted by AMO.
Official references for Toolkit API
- Structure of an Installable Bundle: describes the common structure of installable bundles, including extensions, themes, and XULRunner applications
- Extension Packaging: specific information about how to package extensions
- Theme Packaging: specific information about how to package themes
- Multiple-item Extension Packaging: specific information about multiple-item extension XPIs
- XUL Application Packaging: specific information about how to package XULRunner applications
- Chrome Registration
- Printing in XUL Apps