Manifest V3 migration checklist
This page provides a quick reference to help you identify any changes you might need to make to an Manifest V2 extension so that it works under Manifest V3 (MV3). For more description of the nature of these changes see the MV3 migration guide.
API checklist #
There are some changes you may need to make based on changes to the API surface. This section lists these changes.
Do you have host permissions in your manifest?
Host permissions in MV3 are a separate element; you don't specify them in
- Move host permissions into the
host_permissionsfield in manifest.json.
Are you using background pages?
Background pages are replaced by service workers in MV3.
background.service_workerin manifest.json. Note that the
service_workerfield takes a string, not an array of strings.
- Update background scripts to adapt to the service worker execution context.
Service workers must be registered at root level: they cannot be in a nested directory.
Are you using the
page_action property in manifest.json?
These properties are unified into a single property in MV3.
- Replace these properties with
Are you using the
These two equivalent APIs are unified into a single API in MV3.
- Migrate to the
Are you currently using the blocking version of
This API is replaced by
declarativeNetRequest in MV3.
This only applies to user-installed extensions; force installed extensions (extensions distributed using ExtensionInstallForcelist). These extensions — typically used in an enterprise setting — can still use the blocking version of
- Migrate request modification logic to
- Replace the
- Remove the
webRequestpermission if you no longer need to observe network requests.
- Remove unnecessary host permissions; blocking a request or upgrading a request's protocol doesn't require host permissions with
Are you executing remote code or arbitrary strings?
You can no longer execute external logic using
- Move all external code (JS, Wasm, CSS) into your extension bundle.
- Update script and style references to load resources from the extension bundle.
chrome.runtime.getURL()to build resource URLs at runtime.
Are you executing functions that expect an MV2 background context?
The adoption of service workers in MV3 isn't compatible with methods like
- Migrate to a design that passes messages between other contexts and the background service worker.
Security Checklist #
There are some changes you may need to make based on changes in security policy. This section lists these changes.
Are you making CORS requests in content scripts?
- Move these requests to the background service worker.
Are you using a custom
content_security_policy in manifest.json?
- Remove references to external domains in
style-srcdirectives if present.