Table of contents

How can I use Puppeteer with Chrome extensions?

Yes, you can use Puppeteer with Chrome extensions, but there are specific requirements and limitations to consider. Chrome extensions only work when running Puppeteer in headful mode (not headless) and require special launch arguments.

Basic Setup

To load a Chrome extension with Puppeteer, use the --load-extension and --disable-extensions-except flags:

const puppeteer = require('puppeteer');

async function runWithExtension() {
    const extensionPath = '/absolute/path/to/your/extension';

    const browser = await puppeteer.launch({
        headless: false, // Required for extensions
        args: [
            `--disable-extensions-except=${extensionPath}`,
            `--load-extension=${extensionPath}`,
            '--no-sandbox',
            '--disable-setuid-sandbox'
        ]
    });

    const page = await browser.newPage();
    await page.goto('https://example.com');

    // Your automation code here

    await browser.close();
}

runWithExtension();

Loading Multiple Extensions

You can load multiple extensions by separating paths with commas:

const extensionPaths = [
    '/path/to/extension1',
    '/path/to/extension2',
    '/path/to/extension3'
];

const browser = await puppeteer.launch({
    headless: false,
    args: [
        `--disable-extensions-except=${extensionPaths.join(',')}`,
        `--load-extension=${extensionPaths.join(',')}`
    ]
});

Working with Unpacked Extensions

For development extensions (unpacked), point to the extension directory:

const puppeteer = require('puppeteer');
const path = require('path');

async function runWithUnpackedExtension() {
    // Absolute path to your unpacked extension directory
    const extensionPath = path.resolve(__dirname, 'my-extension');

    const browser = await puppeteer.launch({
        headless: false,
        args: [
            `--disable-extensions-except=${extensionPath}`,
            `--load-extension=${extensionPath}`,
            '--disable-web-security', // Sometimes needed for dev extensions
            '--disable-features=VizDisplayCompositor'
        ]
    });

    const page = await browser.newPage();

    // Wait for extension to load
    await page.waitForTimeout(2000);

    await page.goto('https://example.com');
    await browser.close();
}

Finding Extension Background Pages

You can access extension background pages for debugging:

async function accessExtensionPages() {
    const browser = await puppeteer.launch({
        headless: false,
        args: [`--load-extension=${extensionPath}`]
    });

    // Get all pages (includes extension pages)
    const pages = await browser.pages();

    // Find extension pages
    const extensionPages = pages.filter(page => 
        page.url().startsWith('chrome-extension://')
    );

    console.log('Extension pages:', extensionPages.map(p => p.url()));

    await browser.close();
}

Using User Data Directory

For extensions requiring authentication or persistent data:

const userDataDir = './chrome-user-data';

const browser = await puppeteer.launch({
    headless: false,
    userDataDir: userDataDir,
    args: [
        `--load-extension=${extensionPath}`,
        '--disable-extensions-except=' + extensionPath
    ]
});

Important Limitations

Extension Automation

  • No direct extension UI interaction: You cannot directly click extension buttons or interact with extension popups through Puppeteer
  • Background script access: Limited ability to interact with extension background scripts
  • Content script communication: Possible but requires careful coordination

Technical Constraints

  • Headless mode: Extensions don't work in headless mode (headless: true)
  • Manifest V3: Some newer extensions may have additional restrictions
  • Security policies: Extensions with strict CSP may not function properly

Authentication Issues

  • Profile data: Extensions requiring login won't have saved credentials
  • OAuth flows: May not work properly in automated environments

Common Use Cases

Web Scraping with Ad Blockers

const adBlockerPath = '/path/to/adblocker-extension';

const browser = await puppeteer.launch({
    headless: false,
    args: [`--load-extension=${adBlockerPath}`]
});

const page = await browser.newPage();
await page.goto('https://example.com');
// Page loads with ads blocked

Testing Extension Functionality

async function testExtension() {
    const browser = await puppeteer.launch({
        headless: false,
        args: [`--load-extension=${extensionPath}`]
    });

    const page = await browser.newPage();

    // Test if extension content script loaded
    const extensionLoaded = await page.evaluate(() => {
        return window.myExtensionVariable !== undefined;
    });

    console.log('Extension loaded:', extensionLoaded);
    await browser.close();
}

Troubleshooting Tips

  1. Use absolute paths: Always provide absolute paths to extension directories
  2. Check Chrome version: Ensure extension compatibility with Puppeteer's Chrome version
  3. Wait for loading: Add delays after browser launch to allow extensions to initialize
  4. Check console logs: Monitor browser console for extension errors
  5. Test manually first: Verify the extension works in regular Chrome before automating

Alternative Approaches

If you need headless operation with extension-like functionality: - Inject custom JavaScript that mimics extension behavior - Use proxy servers for request modification - Implement functionality directly in your Puppeteer script

Try WebScraping.AI for Your Web Scraping Needs

Looking for a powerful web scraping solution? WebScraping.AI provides an LLM-powered API that combines Chromium JavaScript rendering with rotating proxies for reliable data extraction.

Key Features:

  • AI-powered extraction: Ask questions about web pages or extract structured data fields
  • JavaScript rendering: Full Chromium browser support for dynamic content
  • Rotating proxies: Datacenter and residential proxies from multiple countries
  • Easy integration: Simple REST API with SDKs for Python, Ruby, PHP, and more
  • Reliable & scalable: Built for developers who need consistent results

Getting Started:

Get page content with AI analysis:

curl "https://api.webscraping.ai/ai/question?url=https://example.com&question=What is the main topic?&api_key=YOUR_API_KEY"

Extract structured data:

curl "https://api.webscraping.ai/ai/fields?url=https://example.com&fields[title]=Page title&fields[price]=Product price&api_key=YOUR_API_KEY"

Try in request builder

Get Started Now

WebScraping.AI provides rotating proxies, Chromium rendering and built-in HTML parser for web scraping
Icon