How to Prepare Your Chrome Extension for Manifest V2 Removal

Chrome Manifest V2 Removal Is Almost Here

Chrome extension developers have reached an important deadline. On August 31, 2026, all remaining Manifest V2 extensions will be removed from the Chrome Web Store. Manifest V2 extensions already stopped functioning on modern Chrome versions when Chrome 139 and later removed their runtime support, so the remaining deadline mainly affects extensions that still need to be migrated, distributed, or maintained through the Chrome Web Store.

For developers who still maintain an older extension, this is not simply a store-listing change. Manifest V2 and Manifest V3 use different extension architectures, permissions, background execution models, and APIs. A successful migration therefore requires more than changing a manifest version number.

What Is Manifest V2?

Manifest V2 is the older Chrome extension platform based on a manifest file that describes an extension's permissions, scripts, background pages, browser actions, and other capabilities.

Many older extensions use a persistent background page, broad host permissions, and APIs that were designed before Chrome moved toward a more constrained extension architecture.

Manifest V3 replaces several of these mechanisms with a service-worker-based background model and introduces tighter controls around permissions, network requests, and extension behavior.

Why Chrome Is Moving to Manifest V3

The move to Manifest V3 is largely about improving the security, privacy, and performance model of browser extensions. Persistent background pages can remain active for long periods, while Manifest V3 uses extension service workers that can be started and stopped by the browser as needed.

This changes how developers must think about application state. An extension can no longer assume that its background context will remain alive indefinitely.

Manifest V3 also changes how extensions handle certain network-request modification tasks. Developers who previously relied on blocking web-request behavior need to review the APIs available to their particular extension rather than assuming the old implementation can simply be copied into the new manifest.

Check Whether Your Extension Still Uses Manifest V2

The first step is straightforward: open your extension's manifest.json file and look for the manifest version.

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0.0"
}

If you see "manifest_version": 2, the extension still uses the older platform.

A Manifest V3 extension instead begins with:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0"
}

Changing this single value does not complete the migration. The rest of the extension must also conform to Manifest V3 requirements.

Back Up Your Existing Extension

Before changing the project, create a separate branch or copy of the working extension. This gives you a reliable reference if a migration change breaks functionality.

git checkout -b migrate-to-manifest-v3
git add .
git commit -m "Backup before Manifest V3 migration"

If your project is not managed with Git, create a complete backup of the extension directory before making changes.

Change the Manifest Carefully

Start by creating a Manifest V3-compatible structure rather than blindly replacing the version number.

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": [],
  "host_permissions": []
}

Some Manifest V2 fields have been renamed, replaced, or removed. For example, extensions that used browser_action generally move to the unified action key in Manifest V3.

Replace Background Pages With Service Workers

One of the biggest migration tasks is replacing a persistent background page with an extension service worker.

A Manifest V2 extension might contain something similar to:

"background": {
  "scripts": ["background.js"],
  "persistent": true
}

Manifest V3 uses a service worker instead:

"background": {
  "service_worker": "background.js"
}

The file may still be called background.js, but its execution model is different. The browser can terminate the service worker when it is no longer needed and start it again when an extension event occurs.

Do Not Store Important State Only in Memory

This is one of the easiest migration mistakes to make.

Suppose your background script previously contained:

let currentUser = null;

With a persistent background page, developers could sometimes rely on that variable remaining available for a long time. A service worker can be terminated, meaning the variable disappears when the worker stops.

Important state should instead be stored using an appropriate persistent mechanism, such as extension storage.

chrome.storage.local.set({
  currentUser: {
    id: 123
  }
});

When the service worker starts again, retrieve the information rather than assuming its previous in-memory state still exists.

Review Event Listeners

Service workers are event-driven. Your background code should register the listeners needed by the extension rather than relying on a script that continuously runs in the background.

chrome.runtime.onInstalled.addListener(() => {
  console.log("Extension installed or updated");
});

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === "hello") {
sendResponse({ ok: true });
}
});

Keep event registration at the top level of the service-worker script. Avoid designing the background logic around long-running processes that assume the worker will remain active.

Review Manifest Permissions

Manifest V3 is an opportunity to reduce the permissions your extension requests.

Separate capabilities that are required for the extension to function from permissions that were added historically but may no longer be necessary.

{
  "permissions": [
    "storage"
  ],
  "host_permissions": [
    "https://example.com/*"
  ]
}

Requesting fewer permissions can make an extension easier for users to trust and can simplify future maintenance.

Check Host Permissions

Older extensions sometimes request access to a very broad range of websites. During migration, review whether the extension really needs access to every host.

For example, instead of using a broad permission covering every website, restrict access to the domains the extension actually supports when possible.

"host_permissions": [
  "https://example.com/*"
]

This is especially important for extensions that inject content scripts or communicate with websites.

Update Browser Action APIs

If your Manifest V2 extension uses browser_action or page_action, check whether the functionality should move to the Manifest V3 action API.

"action": {
  "default_title": "Open Extension",
  "default_popup": "popup.html"
}

The unified action API provides the primary toolbar interaction model for modern Chrome extensions.

Review Content Scripts

Content scripts continue to play an important role in Manifest V3, but their permissions and communication with the service worker need to be reviewed.

{
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "js": ["content.js"]
    }
  ]
}

If your content script communicates with the background service worker, test the complete message flow after migration.

Update Message Passing

Extensions frequently use messages to communicate between popups, content scripts, and background logic. The basic messaging APIs remain useful, but the lifecycle of the receiving service worker is different.

chrome.runtime.sendMessage({
  type: "getStatus"
}).then(response => {
  console.log(response);
});

Design the communication so that the service worker can initialize the information it needs whenever it receives an event.

Be Careful With Long-Running Tasks

A common migration problem occurs when an extension starts a long-running operation inside its background context and assumes the background environment will stay alive.

Instead, use Chrome-supported extension events, alarms, storage, messaging, and other appropriate APIs to structure work around the browser's lifecycle.

If an operation genuinely requires continuous execution, reconsider the architecture rather than attempting to recreate the old persistent background-page behavior.

Review Web Request Logic

If your extension modifies network requests, this part deserves special attention. Manifest V3 changed the architecture and permissions around request handling, and not every Manifest V2 implementation has a direct one-to-one replacement.

Before migrating, identify exactly what your extension does with requests: blocking them, redirecting them, observing them, modifying headers, or simply monitoring traffic.

Then map that requirement to the Manifest V3 APIs and permissions that are actually available for your use case.

Test the Extension Locally

After updating the project, load the unpacked extension in Chrome's extension management interface.

1. Open Chrome's extension management page.
2. Enable Developer mode.
3. Choose the option to load an unpacked extension.
4. Select your Manifest V3 project directory.
5. Check for manifest errors.
6. Open the service-worker inspection tools.
7. Test the popup, content scripts, permissions, messaging, and background events.

Do not stop after confirming that Chrome accepts the manifest. A successful load only proves that the extension structure is valid enough to be loaded. It does not prove that every feature works.

Debug the Service Worker

Service-worker debugging should be part of your migration process. Watch for errors that appear only after the worker starts, stops, and starts again.

Test scenarios such as:

• Opening the extension for the first time.
• Reloading the extension.
• Closing and reopening Chrome.
• Opening multiple tabs.
• Sending messages from content scripts.
• Running scheduled tasks.
• Clearing extension storage.
• Updating the extension.

Lifecycle testing is important because a service worker does not behave like the persistent background page used by many older extensions.

Prepare for the August 31 Deadline

Chrome's published Manifest V2 timeline lists August 31, 2026, as the date when all remaining Manifest V2 extensions are removed from the Chrome Web Store. The browser-side shutdown happened earlier: Chrome 138 was the final version with enterprise mechanisms for keeping Manifest V2 extensions enabled, and Manifest V2 extensions ceased functioning for users upgrading to Chrome 139 and later.

That means developers should not treat the August deadline as the beginning of the migration. If an extension still depends on Manifest V2, the migration work is already overdue.

Manifest V2 vs Manifest V3

Common Migration Mistakes

• Only changing manifest_version: This does not migrate the extension.
• Keeping persistent-background assumptions: Service workers can stop when idle.
• Storing critical state in global variables: The state can disappear when the service worker terminates.
• Copying old permissions: Review whether every permission is still necessary.
• Ignoring network-request changes: Request interception is one of the areas that may require architectural changes.
• Testing only the popup: Background events and content scripts can fail even when the popup appears correctly.
• Waiting until the Web Store deadline: Migration should be completed and tested well before distribution requirements become a problem.

What Developers Should Do Now

1. Check whether the extension still uses Manifest V2.
2. Create a backup or Git branch.
3. Inventory permissions and APIs.
4. Convert background pages to a service worker.
5. Replace outdated manifest keys.
6. Review request-handling logic.
7. Update state management.
8. Test content scripts and messaging.
9. Run the extension through realistic workflows.
10. Prepare the Manifest V3 version for distribution.

Frequently Asked Questions

When will Manifest V2 extensions be removed from the Chrome Web Store?

Chrome's current timeline lists August 31, 2026, for removal of all remaining Manifest V2 extensions from the Chrome Web Store.

Can I simply change Manifest V2 to Manifest V3?

No. Changing the manifest version is only the starting point. Background pages, permissions, APIs, request handling, and lifecycle assumptions may all need changes.

What is the biggest difference between Manifest V2 and V3?

The background execution model is one of the biggest differences. Manifest V3 uses service workers instead of persistent background pages.

Will my extension lose its data during migration?

Changing the manifest does not automatically mean extension storage is lost, but migration code should preserve and validate existing stored data. Always test upgrades with a copy of real-world data before deploying.

Do Manifest V3 extensions still support content scripts?

Yes. Content scripts remain an important part of Chrome extension development, but their permissions, matching rules, and communication with other extension components must be configured correctly.

Final Takeaway

Manifest V3 migration is best treated as an architecture upgrade rather than a simple manifest edit. The most important work is replacing persistent background assumptions, reviewing permissions, adapting request-related functionality, and making sure the extension survives the service-worker lifecycle.

With the August 31, 2026 Chrome Web Store deadline approaching, developers maintaining older extensions should complete the migration, test it against realistic workflows, and move their projects to Manifest V3 rather than waiting for the final removal date.