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.

List of manifest.json keys

manifest.json keys are listed below:

Notes about manifest.json keys

  • "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.

Accessing manifest.json keys at runtime

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 shows the basic syntax for some common manifest keys.

Note: This is not intended to be used as a copy-paste-ready example. Selecting the keys you'll need depends 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"],
  },

  "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

Report problems with this compatibility data on GitHub
webextensions-desktopwebextensions-mobile
ChromeEdgeFirefoxOperaSafariFirefox for Android
author
background
background.page
background.persistent
background.scripts
browser_action
browser_action.browser_style
browser_action.default_area
browser_action.default_icon
browser_action.default_popup
browser_action.default_title
browser_action.theme_icons
browser_specific_settings
chrome_settings_overrides
chrome_settings_overrides.homepage
chrome_settings_overrides.search_provider
search_provider.alternate_urls
search_provider.encoding
search_provider.favicon_url
search_provider.image_url
search_provider.image_url_post_params
search_provider.instant_url
search_provider.instant_url_post_params
search_provider.is_default
search_provider.keyword
search_provider.name
search_provider.prepopulated_id
search_provider.search_url
search_provider.search_url_post_params
search_provider.suggest_url
search_provider.suggest_url_post_params
chrome_settings_overrides.startup_pages
chrome_url_overrides
chrome_url_overrides.bookmarks
chrome_url_overrides.history
chrome_url_overrides.newtab
commands
commands.F1-F12
commands.MediaNextTrack
commands.MediaPlayPause
commands.MediaPrevTrack
commands.MediaStop
Secondary modifier other than Shift
commands.global
commands._execute_sidebar_action
content_scripts
content_scripts.all_frames
content_scripts.css
content_scripts.exclude_globs
content_scripts.exclude_matches
content_scripts.include_globs
content_scripts.js
content_scripts.match_about_blank
content_scripts.matches
content_scripts.run_at
content_security_policy
content_security_policy.content_scripts
content_security_policy.extension_pages
default_locale
description
developer
devtools_page
externally_connectable
homepage_url
icons
incognito
incognito.not_allowed
incognito.spanning
incognito.split
manifest_version
Version 1
DeprecatedNon-standard
Version 2
Version 3
Experimental
name
offline_enabled
omnibox
omnibox.key
optional_permissions
activeTab
background
bookmarks
browserSettings
browsingData
clipboardRead
clipboardWrite
contentSettings
contextMenus
cookies
debugger
downloads
downloads.open
find
geolocation
history
idle
management
notifications
pageCapture
pkcs11
privacy
proxy
sessions
tabHide
tabs
topSites
webNavigation
webRequest
webRequestBlocking
options_page
Deprecated
options_ui
options_ui.browser_style
options_ui.open_in_tab
options_ui.page
page_action
page_action.browser_style
page_action.default_icon
page_action.default_popup
page_action.default_title
page_action.hide_matches
page_action.pinned
page_action.show_matches
permissions
activeTab
alarms
background
bookmarks
browserSettings
browsingData
captivePortal
clipboardRead
clipboardWrite
contentSettings
contextMenus
contextualIdentities
cookies
debugger
dns
downloads
downloads.open
find
geolocation
history
identity
idle
management
menus
nativeMessaging
notifications
pageCapture
pkcs11
privacy
proxy
search
sessions
storage
tabHide
tabs
theme
topSites
unlimitedStorage
webNavigation
webRequest
webRequestBlocking
protocol_handlers
protocol_handlers.dat
protocol_handlers.dweb
protocol_handlers.ftp
protocol_handlers.gopher
protocol_handlers.ipfs
protocol_handlers.ipns
protocol_handlers.ssb
short_name
sidebar_action
sidebar_action.browser_style
sidebar_action.default_icon
sidebar_action.default_panel
sidebar_action.default_title
sidebar_action.open_at_install
storage
storage.managed_schema
theme
theme.colors
colors.accentcolor
DeprecatedNon-standard
colors.bookmark_text
colors.button_background_active
colors.button_background_hover
colors.frame
colors.frame_inactive
colors.frame_incognito
colors.frame_incognito_inactive
colors.icons
colors.icons_attention
colors.ntp_background
colors.ntp_header
colors.ntp_link
colors.ntp_text
colors.popup
colors.popup_highlight
colors.popup_highlight_text
colors.popup_text
colors.tab_background_separator
colors.tab_background_text
colors.tab_line
colors.tab_loading
colors.tab_selected
colors.tab_text
colors.textcolor
DeprecatedNon-standard
colors.toolbar
colors.toolbar_bottom_separator
colors.toolbar_field
colors.toolbar_field_border
colors.toolbar_field_border_focus
colors.toolbar_field_focus
colors.toolbar_field_highlight
colors.toolbar_field_highlight_text
colors.toolbar_field_separator
colors.toolbar_field_text
colors.toolbar_field_text_focus
colors.toolbar_text
colors.toolbar_top_separator
colors.toolbar_vertical_separator
theme.images
images.additional_backgrounds
images.headerURL
DeprecatedNon-standard
images.theme_frame
theme.properties
theme_experiment
ExperimentalNon-standard
theme_experiment.colors
ExperimentalNon-standard
theme_experiment.images
ExperimentalNon-standard
theme_experiment.properties
ExperimentalNon-standard
user_scripts
user_scripts.api_script
version
version_name
web_accessible_resources

Legend

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
See implementation notes.
User must explicitly enable this feature.
Uses a non-standard name.

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

See also

permissions JavaScript API