How to run Puppeteer in a Jupyter notebook
Jupyter starts with a Python kernel, and Puppeteer is a Node.js library that relies on async/await.
The usual IJavaScript kernel does not provide that async support, so Puppeteer code stalls or fails there. The workaround is a patched IJavaScript kernel, ijavascript-await, which adds the async support Puppeteer needs. This guide walks through installing that kernel, installing Puppeteer in the notebook directory, launching Jupyter, and running a first Puppeteer cell.
Why the standard kernel falls short
Puppeteer's API is asynchronous: launching a browser and interacting with a page return promises that you await. A kernel that cannot handle await cannot run that code. The widely used IJavaScript kernel does not add this, so the fix is the patched ijavascript-await package, which extends IJavaScript with async support.
Step 1: install the async-capable kernel
Assuming Jupyter is already installed, install the patched kernel globally with npm so the ijsnotebook launcher becomes available:
Step 2: install Puppeteer in the notebook directory
Puppeteer must be resolvable from where your notebooks live. Run the install from that directory so the require call in a notebook cell can find the package:
Step 3: launch Jupyter with the JavaScript kernel
With both pieces installed, start the notebook server using the convenience launcher that IJavaScript provides:
Step 4: create a JavaScript notebook and pick the kernel
The launcher opens the Jupyter web interface. Create a new JavaScript-based notebook there, then start the kernel for that notebook. The Launch Kernel action is what attaches the async-capable JavaScript kernel to the notebook.
Step 5: import and launch Puppeteer
In a notebook cell, require Puppeteer and launch a browser. The example below launches with headless: false so you can watch the browser window; switch to headless mode if you do not need a visible window. Because the kernel supports await, the launch call can be awaited directly in the cell.
Setup checklist and common failure points
Use this checklist to confirm each stage before moving on:
- Jupyter is installed and the jupyter command works.
- The async-capable kernel is installed globally with npm (the -g flag).
- Puppeteer is installed in the same directory where your notebooks are stored, not only globally.
- Jupyter is started with the ijsnotebook launcher rather than the default Python launcher.
- The new notebook is JavaScript-based and its kernel has been started.
- The first cell uses require('puppeteer') and awaits puppeteer.launch.
If await fails or Puppeteer cannot be found, check the two most common causes first: the standard IJavaScript kernel was used instead of the async-capable one, or Puppeteer was installed in a different directory from the notebook.
Frequently asked questions
Why doesn't the regular IJavaScript kernel work with Puppeteer?
Puppeteer is asynchronous and needs a kernel that supports await. The standard IJavaScript kernel does not provide that support, so the patched ijavascript-await kernel is used instead.
Where should Puppeteer be installed for a notebook?
Install it in the same directory where your notebooks are stored, so the require call in a notebook cell can resolve the package.
Can I run Puppeteer without a visible browser window in Jupyter?
Yes. The example uses headless: false to show the browser, but you can switch to headless mode if you do not need a visible window.