src/headless

Headless Chromium

Headless Chromium allows running Chromium in a headless/server environment. Expected use cases include loading web pages, extracting metadata (e.g., the DOM) and generating bitmaps from page contents -- using all the modern web platform features provided by Chromium and Blink.

As of M118, precompiled headless_shell binaries are available for download under the name chrome-headless-shell via Chrome for Testing infrastructure.

As of M132, headless shell functionality is no longer part of the Chrome binary, so --headless=old has no effect. If you are using old Headless functionality you should now migrate to chrome-headless-shell. Read more.

There are two ways to use Headless Chromium:

Usage via the DevTools remote debugging protocol

1. Start Chrome in headless mode using the --headless command line flag:

$ chrome --headless --remote-debugging-port=9222 https://chromium.org/

2. Navigate to chrome://inspect/ in another instance of Chrome.

Usage from Node.js

For example, the chrome-remote-interface Node.js package can be used to extract a page's DOM like this:

const CDP = require('chrome-remote-interface');

(async () => {
  let client;
  try {
    // Connect to browser
    client = await CDP();

    // Extract used DevTools domains.
    const {Page, Runtime} = client;

    // Enable events on domains we are interested in.
    await Page.enable();
    await Page.navigate({url: 'https://example.com'});
    await Page.loadEventFired();

    // Evaluate outerHTML after page has loaded.
    const expression = {expression: 'document.body.outerHTML'};
    const { result } = await Runtime.evaluate(expression);
    console.log(result.value);

  } catch (err) {
    console.error('Cannot connect to browser:', err);

  } finally {
    if (client) {
      await client.close();
    }
  }
})();

Alternatvely, the Puppeteer Node.js package can be used to communicate with headless, for example:

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch({headless: 'shell'});

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

  const title = await page.evaluate(() => document.title);
  console.log(title);

  await browser.close();
})();

Resources and Documentation

Mailing list: headless-dev@chromium.org

Bug tracker: Internals>Headless

File a new bug (bit.ly/2pP6SBb)

• Runtime headless mode on Windows OS
• BeginFrame sequence numbers + acknowledgements
• Deterministic page loading for Blink
• Crash dumps for Headless Chrome
• Runtime headless mode for Chrome
• Virtual Time in Blink
• Headless Chrome architecture (Design Doc)
• Session isolation in Headless Chrome
• Headless Chrome mojo service
• Controlling BeginFrame through DevTools
• Viewport bounds and scale for screenshots
• BlinkOn 6 presentation slides