manifest.json

Note: 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

These are the manifest.json keys; these keys are available in Manifest V2 and above unless otherwise noted:

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:

js
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.

json
{
  "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

Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
action
action.browser_style
action.default_area
action.default_icon
action.default_popup
action.default_title
action.theme_icons
author
background
background.page
background.persistent
background.scripts
background.service_worker
background.type
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
browser_specific_settings.gecko
browser_specific_settings.gecko_android
browser_specific_settings.safari
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._execute_action
commands._execute_browser_action
commands._execute_page_action
commands._execute_sidebar_action
commands.global
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.match_origin_as_fallback
content_scripts.matches
content_scripts.run_at
content_scripts.world
content_security_policy
content_security_policy.extension_pages
content_security_policy.sandbox
declarative_net_request
declarative_net_request.rule_resources
rule_resources.enabled
rule_resources.id
rule_resources.path
default_locale
description
developer
devtools_page
dictionaries
externally_connectable
homepage_url
host_permissions
icons
SVG icons
incognito
incognito.not_allowed
incognito.spanning
incognito.split
manifest_version
Version 2
Version 3
name
offline_enabled
omnibox
omnibox.keyword
optional_permissions
activeTab
alarms
background
bookmarks
browserSettings
browsingData
clipboardRead
clipboardWrite
contentSettings
contextMenus
cookies
declarativeNetRequest
declarativeNetRequestFeedback
declarativeNetRequestWithHostAccess
devtools
dns
downloads
downloads.open
find
geolocation
history
identity
idle
management
nativeMessaging
notifications
pageCapture
pkcs11
privacy
proxy
scripting
search
sessions
storage
tabHide
tabs
topSites
unlimitedStorage
webNavigation
webRequest
webRequestBlocking
webRequestFilterResponse
webRequestFilterResponse.serviceWorkerScript
options_page
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
declarativeNetRequest
declarativeNetRequestFeedback
declarativeNetRequestWithHostAccess
devtools
dns
downloads
downloads.open
find
geolocation
history
identity
idle
management
menus
nativeMessaging
notifications
pageCapture
pkcs11
privacy
proxy
scripting
search
sessions
storage
tabHide
tabs
theme
topSites
unlimitedStorage
webNavigation
webRequest
webRequestAuthProvider
webRequestBlocking
webRequestFilterResponse
webRequestFilterResponse.serviceWorkerScript
protocol_handlers
protocol_handlers.dat
protocol_handlers.dweb
protocol_handlers.ftp
protocol_handlers.gopher
protocol_handlers.ipfs
protocol_handlers.ipns
protocol_handlers.matrix
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.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.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.theme_frame
theme.properties
properties.color_scheme
properties.content_color_scheme
theme_experiment
theme_experiment.colors
theme_experiment.images
theme_experiment.properties
user_scripts
user_scripts.api_script
version
version_name
web_accessible_resources
web_accessible_resources.extension_ids
web_accessible_resources.matches
web_accessible_resources.resources
web_accessible_resources.use_dynamic_url

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