2026.07.07

Puppeteerでold Headless deprecation warningが出た時の対処法

saratogax

記事内に商品プロモーションを含む場合があります

Puppeteer を実行していて、いつの日か以下の警告が出ていることに気付く。

どうやら近いうちに、「headless: true」の設定がデフォルトで新しいヘッドレスモードになるとのこと。

Puppeteer old Headless deprecation warning:
    In the near feature `headless: true` will default to the new Headless mode
    for Chrome instead of the old Headless implementation. For more
    information, please see https://developer.chrome.com/articles/new-headless/.
    Consider opting in early by passing `headless: "new"` to `puppeteer.launch()`
    If you encounter any bugs, please report them to https://github.com/puppeteer/puppeteer/issues/new/choose.

2023 年の 2 月くらいから警告が出ていたのでしょうか。

この警告は、将来的には意図しない挙動になったり、サポートされなくなることが予想されるため、早めに対処しておくのがベターですね。

今回はこの警告が出なくなるような対応をしていきます。

Contents

警告の原因
警告の対応
【追記】現在のPuppeteer(v22以降)での指定方法
まとめ
- 参考（出典）

警告の原因

Chrome のヘッドレスモードが大幅に改善されたことと、「headless=new」が導入されたことがトリガーで出力されるようになったようですね。

Chrome’s Headless mode gets an upgrade: introducing --headless=new

新しいものを選択しようが、古いものを選択しようが、こだわりがなければ放置でもいいと思うのですが、警告が出るのは気持ち悪い。

警告の対応

ということで Puppeteer の場合は、以下のサンプルコードが提供されています。

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: 'new',
  // `headless: true` (default) enables old Headless;
  // `headless: 'new'` enables new Headless;
  // `headless: false` enables “headful” mode.
});

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

// …

await browser.close();

launch のコンストラクタに、headless を指定するようですね。

headlessの設定値	挙動
true(default)	enables old Headless
new	enables new Headless
false	enables “headful” mode

では、headless に new を指定してみましょう。

(async () => {
  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();
  await page.setExtraHTTPHeaders({
    'Accept-Language': 'xx',
    'User-Agent': 'xxxxxx'
  });
  await page.goto(url, { waitUntil: 'networkidle0' });
  const res = await page.evaluate(() => {
    return document.body.outerHTML;
  });
  console.log(res);

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

想定通り、冒頭の警告が出力されなくなりました。

【追記】現在のPuppeteer(v22以降)での指定方法

上記は警告が出ていた当時（2023 年頃）の対処法です。

その後 Puppeteer は v22（2024 年）で挙動が変わり、headless: true がそのまま新ヘッドレスモードを指すようになりました。

そのため、現在のバージョンではこの警告自体が出なくなり、headless: ‘new’ という指定も不要です（’new’ は公式ドキュメントからも姿を消しました）。

新しくコードを書くなら、次のように headless: true（または省略）でOKです。

// 現在のデフォルト（新ヘッドレスモード）
const browser = await puppeteer.launch();
// 明示するなら headless: true

// 旧ヘッドレスモード（chrome-headless-shell）を使いたい場合のみ
const browser = await puppeteer.launch({ headless: 'shell' });

現行の headless オプションの選択肢を整理すると、次のとおりです。

headlessの設定値	挙動
true(default)	新ヘッドレスモード（v22 以降の既定）
‘shell’	旧ヘッドレスモード（chrome-headless-shell・軽量）
false	ヘッドフル（GUIあり）