manifest.json

This article describes manifest.json for web extensions. If you are looking for information about the manifest.json in PWAs, check out the Web App Manifest article.

The manifest.json file is the only file that every extension using WebExtension APIs must contain.

Using manifest.json, you specify basic metadata about your extension such as the name and version, and can also specify aspects of your extension's functionality, such as background scripts, content scripts, and browser actions.

It is a JSON-formatted file, with one exception: it is allowed to contain "//"-style comments.

manifest.json keys are listed below:

"manifest_version", "version", and "name" are the only mandatory keys. "default_locale" must be present if the "_locales" directory is present and must be absent otherwise. "browser_specific_settings" is not supported in Google Chrome.

You can access your extension's manifest from the extension's JavaScript using the runtime.getManifest() function:

browser.runtime.getManifest().version;

Example

The block below contains shows the basic syntax for some common manifest keys. Note that it is not intended to be used as a copy-paste-ready example: which keys you need will depend on the extension you are developing. For complete example extensions, see Example extensions.

{
  "browser_specific_settings": {
    "gecko": {
      "id": "addon@example.com",
      "strict_min_version": "42.0"
    }
  },

  "background": {
    "scripts": ["jquery.js", "my-background.js"],
    "page": "my-background.html"
  },

  "browser_action": {
    "default_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default_title": "Whereami?",
    "default_popup": "popup/geo.html"
  },

  "commands": {
    "toggle-feature": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "linux": "Ctrl+Shift+U"
      },
      "description": "Send a 'toggle-feature' event"
    }
  },

  "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",

  "content_scripts": [
    {
      "exclude_matches": ["*://developer.mozilla.org/*"],
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ],

  "default_locale": "en",

  "description": "...",

  "icons": {
    "48": "icon.png",
    "96": "icon@2x.png"
  },

  "manifest_version": 2,

  "name": "...",

  "page_action": {
    "default_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default_title": "Whereami?",
    "default_popup": "popup/geo.html"
  },

  "permissions": ["webNavigation"],

  "version": "0.1",

  "user_scripts": {
    "api_script": "apiscript.js",
  },

  "web_accessible_resources": ["images/my-image.png"]
}

Browser compatibility

For a full overview of all manifest keys and their sub-keys, see the full manifest.json browser compatibility table.

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
authorChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes This key is mandatory in Microsoft Edge.
Firefox Full support 52Opera Full support YesFirefox Android Full support 52
backgroundChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
browser_actionChrome Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a browser action, it is not allowed to define a page action as well.
Edge Full support 14Firefox Full support 48Opera Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a browser action, it is not allowed to define a page action as well.
Firefox Android Full support 55
browser_specific_settingsChrome No support NoEdge Full support 15Firefox Full support 48
Full support 48
Full support 42
Notes Alternate Name
Notes Mandatory before Firefox 48.
Alternate Name Uses the non-standard name: applications
Opera No support NoFirefox Android Full support 48
Full support 48
Full support 42
Notes Alternate Name
Notes Mandatory before Firefox 48.
Alternate Name Uses the non-standard name: applications
chrome_settings_overridesChrome Full support YesEdge No support NoFirefox Full support 55Opera No support NoFirefox Android No support No
chrome_url_overridesChrome Full support YesEdge No support NoFirefox Full support 54Opera No support NoFirefox Android No support No
commandsChrome Full support YesEdge No support NoFirefox Full support 48Opera Full support YesFirefox Android No support No
content_scriptsChrome Full support Yes
Notes
Full support Yes
Notes
Notes Content scripts are not applied to tabs already open when the extension is loaded.
Edge Full support 14Firefox Full support 48Opera Full support Yes
Notes
Full support Yes
Notes
Notes Content scripts are not applied to tabs already open when the extension is loaded.
Firefox Android Full support 48
content_security_policyChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes Only the default content security policy is supported: "script-src 'self'; object-src 'self';".
Firefox Full support 48
Notes
Full support 48
Notes
Notes Firefox does not support 'http://127.0.0.1' or 'http://localhost' as script sources: they must be served over HTTPS.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes Firefox does not support 'http://127.0.0.1' or 'http://localhost' as script sources: they must be served over HTTPS.
default_localeChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
descriptionChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
developerChrome No support NoEdge No support NoFirefox Full support 52Opera Full support YesFirefox Android Full support 52
devtools_pageChrome Full support YesEdge No support NoFirefox Full support 54Opera Full support YesFirefox Android No support No
externally_connectableChrome Full support YesEdge No support NoFirefox No support No
Notes
No support No
Notes
Notes See bug 1319168.
Opera Full support YesFirefox Android No support No
homepage_urlChrome Full support YesEdge No support NoFirefox Full support 48Opera Full support YesFirefox Android Full support 48
iconsChrome Full support Yes
Notes
Full support Yes
Notes
Notes Chrome does not support SVG format for icons. It is recommended to use PNG images.
Edge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
incognitoChrome Full support YesEdge Full support YesFirefox Full support 48Opera Full support YesFirefox Android Full support 48
manifest_versionChrome Full support 4Edge Full support 14Firefox Full support 48Opera Full support 15Firefox Android Full support 48
nameChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
offline_enabledChrome Full support YesEdge No support NoFirefox No support NoOpera Full support YesFirefox Android No support No
omniboxChrome Full support YesEdge No support NoFirefox Full support 52Opera Full support YesFirefox Android No support No
optional_permissionsChrome Full support YesEdge No support NoFirefox Full support 55Opera Full support YesFirefox Android Full support 55
options_page
Deprecated
Chrome Full support YesEdge Full support 14Firefox No support NoOpera Full support 15Firefox Android No support No
options_uiChrome Full support 40Edge No support NoFirefox Full support 48Opera Full support 27Firefox Android Full support 57
page_actionChrome Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a page action, it is not allowed to define a browser action as well.
Full support 49
Notes
Notes Since Chrome 49, page actions are displayed on the toolbar, rather than in the address bar.
Edge Full support 14Firefox Full support 48Opera Full support Yes
Notes
Full support Yes
Notes
Notes If an extension defines a page action, it is not allowed to define a browser action as well.
Firefox Android Full support Yes
permissionsChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
protocol_handlersChrome No support NoEdge No support NoFirefox Full support 54Opera No support NoFirefox Android Full support 54
short_nameChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
sidebar_actionChrome No support NoEdge No support NoFirefox Full support 54Opera Full support 30Firefox Android No support No
themeChrome Full support YesEdge No support NoFirefox Full support 55Opera No support NoFirefox Android Full support Yes
theme_experimentChrome No support NoEdge No support NoFirefox Full support 63Opera No support NoFirefox Android No support No
versionChrome Full support Yes
Notes
Full support Yes
Notes
Notes Valid Chrome versions are a subset of valid Firefox versions.
Edge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48
version_nameChrome Full support YesEdge No support NoFirefox No support NoOpera Full support YesFirefox Android No support No
web_accessible_resourcesChrome Full support YesEdge Full support 14Firefox Full support 48Opera Full support YesFirefox Android Full support 48

Legend

Full support  
Full support
No support  
No support
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.
Uses a non-standard name.
Uses a non-standard name.