Replace deprecated --load-extension with Extensions.loadUnpacked CDP to continue "web-ext run" support in Chrome

[Rob--W]

Chrome is looking into removing the --load-extension flag. web-ext run currently relies on --load-extension to load/run an extension and to load a helper extension (whose purpose is to reload the extension on demand). When --load-extension is removed, web-ext run will be unable to load extensions in Chrome (and Chromium based browsers that follow the same implementation).

A supported alternative to --load-extension is the Extensions.loadUnpacked Chrome DevTools Protocol (CDP) command:
https://chromedevtools.github.io/devtools-protocol/tot/Extensions/#method-loadUnpacked

To use this, Chrome's DevTools server has to be set up with --remote-debugging-pipe instead of --remote-debugging-port. But the chrome-launcher library that web-ext relies on right now hardcodes a dependency on --remote-debugging-pipe.

For reference, Puppeteer supports pipes (and port):

• https://github.com/puppeteer/puppeteer/blob/5b777616198ae31625b9b2c1eba82c0968b82340/packages/puppeteer-core/src/node/ChromeLauncher.ts#L86-L100
• https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/BrowserLauncher.ts#L112-L140
• https://github.com/puppeteer/puppeteer/blob/5b777616198ae31625b9b2c1eba82c0968b82340/packages/puppeteer-core/src/node/PipeTransport.ts

Ideally, chrome-launcher would also accept a mechanism to switch to a pipe-based communication.

For visibility, here is an issue about switching to WebDriver BiDi in Firefox: #3351. If the mechanisms to use WebDriver BiDi are similar (without too much overhead/dependencies), it would be nice to use WebDriver BiDi for both. However, since the --load-extension deprecation is landing soon, we should not block on that for this issue.

[oliverdunk]

Thanks for filing this Rob! We've just confirmed that we are moving forward with this change: https://groups.google.com/a/chromium.org/g/chromium-extensions/c/1-g8EFx2BBY/m/S0ET5wPjCAAJ

[Rob--W]

Chrome 137 is scheduled for beta next week (30 april) and targeting release 20 May 2025, per https://chromiumdash.appspot.com/schedule

I'll try to find a weekend or so to look into fixing this.

[Rob--W]

While looking into this, I also noticed that Chrome is also phasing out support for debugging the default profile: https://source.chromium.org/chromium/chromium/src/+/c7debf96ebebaf6b50e8a90e23c15ee66c2e967f

[Rob--W]

Another potential issue: When --remote-debugging-pipe is used, navigator.webdriver becomes true (Blink source). This could result in a different user experience on some websites, e.g. bot/automation detection can check this flag.

It is possible to have navigator.webdriver==false by passing --disable-blink-features=AutomationControlled, but a side of that is that an infobar is shown with the text: You are using an unsupported command-line flag: --disable-blink-features=AutomationControlled. Stability and security will suffer., which may be annoying.

The navigator.webdriver flag is not set when --remote-debugging-port is used (except when set to 0) (Blink source 2).

[Rob--W]

I put up a pull request for the change in chrome-launcher, including a unit test that shows how one can load extensions: GoogleChrome/chrome-launcher#347

[Rob--W]

chrome-launcher@1.2.0 includes the patch that I submitted to chrome-launcher, and was just merged in #3412. I'll add a patch to web-ext that uses --remote-debugging-pipe where feasible.

For reference, a tested and approved way to load extensions can be seen in the unit tests that I included at https://github.com/GoogleChrome/chrome-launcher/blob/89c4456e9211380b3ed00d0ceeb10e6f23f1c6e5/test/load-extension-test.ts

[Rob--W]

In order to support the new requirements while still having reasonable support for previous versions, I did some digging and testing with various Chrome versions. Based on the observed results and various degrees of --load-extension being broken, I'm inclined to use the Extensions.loadUnpacked feature where possible. When unsupported, we can fall back to --load-extension.

There is still a question on what to do with navigator.webdriver (#3388 (comment)), and I'll write about that in a separate comment.

Some overview of historical information (dates for Chrome version match "Stable Release" as published at https://chromiumdash.appspot.com/schedule ):

• 2018-04-17: Chrome 66: Introduced --remote-debugging-pipe support to browser (no bug, commit: https://chromiumdash.appspot.com/commit/c9ae59c8f37d487f1f01c222deb6b7d1f51c99c2 )
• 2018-09-04: Chrome 69: the first version where I confirmed that --remote-debugging-pipe works (on Linux, test case below)
• 2019-09-27: web-ext@3.2.0 released with support for web-ext run --target=chromium (at the time of release, Chrome 77 was the then stable version)
• 2021-01-19: Chrome 88: Manifest Version 3 support generally available (WIP MV3 implementation started earlier, background service worker basics were introduced in 75). Since Chrome started deprecating MV2 and discontinues support in June 2025, developers are likely developing MV3-only extensions, and there is no real point in supporting Chrome 87 and earlier.
• 2023-08-15: Chrome 116+ Disable --load-extension when Enhanced Safe Browsing is enabled (restricted bug, relevant commit: https://chromiumdash.appspot.com/commit/c7dd50a6e738be40ff09edc4236a64acf035465c)
• 2023-12-05: Chrome 120+: Disable --load-extension when set by enterprise policies ( https://issues.chromium.org/issues/40276608 )
• 2024-06-11: Chrome 126+: Introduced Extensions.loadUnpacked support, with --allow-unsafe-extension-debugging ( https://issues.chromium.org/issues/332667705 ; restricted bug, relevant commit: https://chromiumdash.appspot.com/commit/225b2eaa7f23c33b7c4e30c1bfc58f1bd99cbe1c )
• 2025-03-04: Chrome 134+: When Developer Mode is off, Extensions installed with --load-extension flag were disabled upon reload ( https://issues.chromium.org/issues/362756477 ). It is currently possible to disable the restriction with --disable-features=DisableLoadExtensionCommandLineSwitch, but this is unlikely to be a long-term solution.
• 2025-05-27: Chrome 137+: --load-extension disabled by default in official builds; non-official builds can still use it for now ( https://issues.chromium.org/issues/401529219 ).
• 2025-08-05: Chrome 139+: MV2 extension support will be dropped (https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline)

The replacement for --load-extension was introduced one year ago (Chrome 126). Before its support, an attempt to use the protocol yielded an error message, and the error is consistent. I spot-checked Chrome 69, 70, 77, 88, 100, 122, 125 (error cases), 126, 134, 140 (supported cases):

Example of commands to test the expected results::

$ mkfifo fifop
$ printf '{"id": 1, "method": "Extensions.loadUnpacked", "params": { "path": "/tmp/testext" } }\0' >> fifop &

$ exec 3<>fifop 4>&1; /path/to/chromium --user-data-dir=/tmp/testdir --remote-debugging-pipe --enable-unsafe-extension-debugging
{"error":{"code":-32601,"message":"'Extensions.loadUnpacked' wasn't found"},"id":1}
{"id":1,"error":{"code":-32601,"message":"'Extensions.loadUnpacked' wasn't found"}}
(older versions had "id" at front, newer versions have "id" at end)

Error when the path is non-existent:

{"id":1,"error":{"code":-32600,"message":"Manifest file is missing or unreadable"}}

Error when trying to load a MV2 extension (output of Chrome 140):

{"id":1,"error":{"code":-32600,"message":"Cannot install extension because it uses an unsupported manifest version."}}

Error when --enable-unsafe-extension-debugging is not set:

{"id":1,"error":{"code":-32000,"message":"Method not available."}}

Result when the extension loaded successfully:

{"id":1,"result":{"id":"nhfegjmejogoggehfdcndoikgdlncfph"}

Testing force-disabling --load-extension even on non-official builds:

$ /path/to/chromium --user-data-dir=/tmp/testdir --load-extension=/tmp/testext --enable-features=DisableLoadExtensionCommandLineSwitch --enable-logging=stderr
...
[2022177:2022177:0524/203346.686195:WARNING:chrome/browser/extensions/extension_service.cc:359] --load-extension is not allowed in Google Chrome, ignoring.

Testing force-enabling --load-extension (even on official builds, provided that it is not disabled through Enhanced Safe Browsing or Enterprise policies, which is the case by default):

$ /path/to/chromium --user-data-dir=/tmp/testdir --load-extension=/tmp/testext --disable-features=DisableLoadExtensionCommandLineSwitch

[Rob--W]

About navigator.webdriver being set to true when --remote-debugging-pipe is in use (#3388 (comment)).

I can think of the following approaches:

Pass --disable-blink-features=AutomationControlled. A side effect of that is that an infobar is shown with the text: You are using an unsupported command-line flag: --disable-blink-features=AutomationControlled. Stability and security will suffer.

Load an extension that sets navigator.webdriver to false. This only works on pages where a content script can be injected.

Do nothing. Then navigator.webdriver is true, and pages can potentially change the debugging experience. For example, here is a report of a user being unable to log in to Google services: https://issues.chromium.org/issues/40746300

Short-term option: pass --disable-features=DisableLoadExtensionCommandLineSwitch to continue support for --load-extension, until Chrome removes it.