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.preferred_environment
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_get_params
search_provider.search_url_post_params
search_provider.suggest_url
search_provider.suggest_url_get_params
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.css_origin
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_host_permissions
optional_permissions
optional_permissions.activeTab
optional_permissions.alarms
optional_permissions.background
optional_permissions.bookmarks
optional_permissions.browserSettings
optional_permissions.browsingData
optional_permissions.clipboardRead
optional_permissions.clipboardWrite
optional_permissions.contentSettings
optional_permissions.contextMenus
optional_permissions.cookies
optional_permissions.declarativeNetRequest
optional_permissions.declarativeNetRequestFeedback
optional_permissions.declarativeNetRequestWithHostAccess
optional_permissions.devtools
optional_permissions.dns
optional_permissions.downloads
downloads.open
optional_permissions.find
optional_permissions.geolocation
optional_permissions.history
optional_permissions.identity
optional_permissions.idle
optional_permissions.management
optional_permissions.menus
optional_permissions.nativeMessaging
optional_permissions.notifications
optional_permissions.pageCapture
optional_permissions.pkcs11
optional_permissions.privacy
optional_permissions.proxy
optional_permissions.scripting
optional_permissions.search
optional_permissions.sessions
optional_permissions.storage
optional_permissions.tabHide
optional_permissions.tabs
optional_permissions.topSites
optional_permissions.unlimitedStorage
optional_permissions.webNavigation
optional_permissions.webRequest
optional_permissions.webRequestBlocking
optional_permissions.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
permissions.activeTab
permissions.alarms
permissions.background
permissions.bookmarks
permissions.browserSettings
permissions.browsingData
permissions.captivePortal
permissions.clipboardRead
permissions.clipboardWrite
permissions.contentSettings
permissions.contextMenus
permissions.contextualIdentities
permissions.cookies
permissions.debugger
permissions.declarativeNetRequest
permissions.declarativeNetRequestFeedback
permissions.declarativeNetRequestWithHostAccess
permissions.devtools
permissions.dns
permissions.downloads
downloads.open
permissions.find
permissions.geolocation
permissions.history
permissions.identity
permissions.idle
permissions.management
permissions.menus
permissions.nativeMessaging
permissions.notifications
permissions.pageCapture
permissions.pkcs11
permissions.privacy
permissions.proxy
permissions.scripting
permissions.search
permissions.sessions
permissions.storage
permissions.tabHide
permissions.tabs
permissions.theme
permissions.topSites
permissions.unlimitedStorage
permissions.webNavigation
permissions.webRequest
permissions.webRequestAuthProvider
permissions.webRequestBlocking
permissions.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