To run a Chrome extension in an unattended scraping workflow, use Chrome’s unified Headless mode—not the old Headless Shell—and load the extension through your automation framework. In Puppeteer, pass the unpacked extension directory in enableExtensions or install it at runtime. Then test the extension’s content script, action or popup, and (for Manifest V3) service worker separately. These steps explain browser automation; they do not grant permission to collect data from any particular website.
Does headless Chrome support extensions?
Yes, when you use Chrome’s unified Headless mode. Chrome’s extension end-to-end testing guide says to start with --headless=new; the old Headless mode does not support loading extensions. Chrome describes unified Headless as Chrome running without a visible UI. The old mode is now distributed separately as chrome-headless-shell, beginning with Chrome 132.0.6793.0. See Chrome’s extension testing guide and its Headless overview, last updated 2024-10-21.
In Puppeteer, headless: true selects Chrome Headless, headless: 'shell' selects Headless Shell, and headless: false runs headful Chrome. Because defaults and browser selection can change, check the installed browser version and the actual launch arguments. If extension loading fails, verify that the run is using unified Headless rather than the shell binary or old mode.
Check permission before building a scraper
A browser’s ability to load an extension says nothing about whether a target permits automated access or collection. Before running a workflow, review the site’s terms and technical access rules, and assess the applicable law, privacy obligations, data type, jurisdiction, and any authorization requirements. The technical sources cited here do not resolve those questions for a particular target.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Load an unpacked extension with Puppeteer
Puppeteer documents two ways to use an unpacked extension: provide its directory when launching the browser, or enable extension support and install it during the session. The extension directory should contain the extension’s packaged files, including its manifest. This example uses the launch-time method:
import puppeteer from 'puppeteer';
import path from 'node:path';
const pathToExtension = path.join(process.cwd(), 'my-extension');
const browser = await puppeteer.launch({
headless: true,
enableExtensions: [pathToExtension],
});
try {
const page = await browser.newPage();
await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });
// Inspect the page and extension behavior for your permitted use.
} finally {
await browser.close();
}Use a current Puppeteer release and confirm its browser launch resolves to unified Headless. Chrome’s extension guide specifically calls out --headless=new; if your installed framework/browser combination does not select that mode, configure the current launch API’s Chrome arguments accordingly. Avoid blindly combining flags from old examples, since the browser binary and supported options depend on the version in use.
Install the extension at runtime instead
If the extension path is only known after launch, Puppeteer documents enabling extensions and installing one in the browser session:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
headless: true,
enableExtensions: true,
});
try {
const extensionId = await browser.installExtension('/absolute/path/to/my-extension');
const page = await browser.newPage();
await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });
console.log('Installed extension:', extensionId);
} finally {
await browser.close();
}Use an absolute path when practical so the job does not depend on its working directory. Puppeteer also documents enumerating installed extensions and uninstalling them, which is useful when a test manages multiple extensions. See the Puppeteer Chrome Extensions guide for the current API and examples.
Test the extension surface your workflow actually needs
An extension is not a single action that automatically runs on every page. A scraper workflow should verify the particular extension behavior it relies on rather than treating successful browser startup as proof that the extension works.
Content script on a navigated page
Navigate to a URL that matches the extension’s content-script match rules, then assert the expected page behavior or extracted value. Puppeteer says content scripts are injected normally on navigation and documents page.extensionRealms() for evaluating code in a content-script context. A passing check should confirm the script can see the intended rendered page, not merely that the extension is installed.
Action or popup flow
If the workflow depends on a user-triggered action or popup, trigger that action and inspect the resulting UI or page effect. Puppeteer documents triggering the extension action and observing or opening its popup. This check covers the user-interaction path; it does not establish that the action runs on every navigation.
Manifest V3 service worker
For background work, wait for the extension’s service_worker target and check the event-driven behavior your workflow depends on. Puppeteer’s guide shows how to find that target. Chrome’s general guide also demonstrates extension page URLs in the chrome-extension://<id>/ form. Prefer observable effects in integration tests; inspect internal state only when it gives necessary coverage.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDesign for Manifest V3’s service-worker lifecycle
Manifest V3 replaces the persistent background-page model with extension service workers that run when needed. A worker may stop between events, so do not build correctness around a background process staying awake continuously. Structure work around events and persist state that must survive an invocation. Chrome documents the lifecycle and related Manifest V3 changes in its Manifest V3 overview.
Manifest V3 also restricts remotely hosted executable code in ordinary extension logic. Chrome Web Store guidance says the extension’s functionality must be discernible from submitted code; common policy violations include loading remote scripts, executing fetched strings with eval(), and interpreting remote commands as code. Remote data or configuration may be fetched in specified circumstances, but the logic itself must remain packaged. If a server supplies selectors or settings, keep that material inert data rather than remotely delivered executable behavior, and check the current policy before release. See Chrome Web Store’s Manifest V3 requirements, last updated 2024-04-03.
Choose an automation library and browser mode
Chrome’s end-to-end extension testing guidance names Puppeteer and Playwright, Selenium with ChromeOptions, and WebDriverIO as automation-library options. The sources establish extension-testing approaches, not a performance ranking or a comparison of scraping throughput, compatibility, evasion, or operating cost.
| Choice | What the guidance establishes | Practical decision |
|---|---|---|
| Unified Chrome Headless | Chrome’s documented headless route for extension testing. | Use it for an unattended run that needs an extension. |
| Old Headless / Headless Shell | Chrome’s extension guide says the old mode does not support loading extensions; the shell is separately available beginning with Chrome 132.0.6793.0. | Do not use it for an extension-dependent workflow. |
| Puppeteer | Documents launch-time extension paths, runtime installation, and ways to exercise extension surfaces. | Use its extension APIs and verify the browser mode selected by your installed combination. |
| Playwright, Selenium, WebDriverIO | Named by Chrome as extension-testing library options. | Follow the current API for the chosen library; do not assume Puppeteer’s option names apply. |
Troubleshoot common extension failures
- Extension is missing in Headless: Check whether the browser is using old Headless or
chrome-headless-shell. Configure unified Headless and confirm the actual executable and launch flags. - Extension does not appear to run on a page: Verify that the navigated URL matches the content script’s declared URL patterns and permissions, and that you navigate after the extension has loaded.
- Popup or action test finds nothing: Confirm the extension defines the action/popup you expect and explicitly trigger the action; it is not equivalent to a page-load content script.
- Background work disappears between checks: Treat an MV3 service worker as event-driven, not persistent. Trigger the event under test and persist required state outside the worker’s in-memory lifetime.
- Install fails or wrong files load: Point to the unpacked extension root containing its manifest, use an absolute path, and inspect the extension’s installation/load errors before investigating scraping logic.
- Behavior differs across machines: Record the Chrome version, automation-library version, executable path, and launch arguments. Version-sensitive defaults can change which headless mode actually runs.
- Extension rejected for policy reasons: Keep executable logic packaged in the extension and review current Manifest V3 and Web Store policy for any remote configuration or code-loading design.
Or skip the browser setup
If your goal is a clean page screenshot rather than running your own extension logic, ScreenshotNeo offers a screenshot API and MCP server. A single GET request accepts a URL and returns an image or PDF. Its clean-shot steps accept cookie/consent banners like a visitor and remove 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with the outcome identified in response headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For API parameters and options, see the ScreenshotNeo documentation. This cURL example saves a WebP screenshot of the target URL:
Best Value
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpThe same endpoint can be called from Python or Node.js:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
- Cookie banners, popups, and chat widgets are removed before the shot.
- Bot checks, blank pages, and failed loads are never billed.
- An MCP server lets AI agents take screenshots.
- The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Can I use the old Headless Shell if I need an extension?
No. Chrome’s extension testing guidance says the old Headless mode does not support loading extensions; use unified Headless.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsDoes this setup make scraping a site legal or authorized?
No. Permission depends on the target, data, jurisdiction, and use case; review applicable terms, access rules, and legal and privacy requirements before collecting data.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
