Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Short answer: Puppeteer is a Node.js library, so a standard Python Jupyter kernel cannot import it directly. Use a JavaScript-capable kernel, or keep the Python kernel and call a Node.js script as a subprocess. Install the puppeteer package in a Node project (it normally downloads a compatible Chrome for Testing browser), launch the browser asynchronously, and close it after each task. If you use puppeteer-core, you must provide an existing Chrome or Chromium executable.
Choose the notebook architecture first
Jupyter starts with an IPython/Python kernel by default. Puppeteer runs in JavaScript under Node.js, not inside Python. Jupyter supports other languages through additional kernels, so there are two dependable designs:
| Design | Best for | What runs Puppeteer | Main trade-off |
|---|---|---|---|
| JavaScript kernel | Interactive browser work, repeated cells, JavaScript results | A Node.js kernel attached to Jupyter | Requires installing and registering a JavaScript kernel |
| Python kernel plus Node subprocess | Python data pipelines that occasionally need a browser | A separate Node script launched by Python | You pass input and output across a process boundary |
There is no single official “Puppeteer in Jupyter” command. The kernel or subprocess arrangement is your decision; Puppeteer itself remains a Node library.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Prerequisites and installation
Install Jupyter
In a Python environment, install Notebook with:
python -m pip install notebook
jupyter notebookJupyterLab can be installed and started similarly with python -m pip install jupyterlab followed by jupyter lab. Keep the Python environment activated when you start Jupyter so its kernels and subprocesses resolve predictably.
#1 Best Overall
Install a supported Node.js version
The current Puppeteer system-requirements page lists Node.js 22.12 or newer for its current release line. Check the version visible to the same user and environment that will run your notebook:
node --version
npm --versionIf a notebook server is managed by Docker, a hosted service or a system administrator, verify Node is on the server, not only on your laptop.
Create a Node project and install Puppeteer
From a project directory:
mkdir jupyter-puppeteer
cd jupyter-puppeteer
npm init -y
npm install puppeteerThe full puppeteer package normally downloads a matching Chrome for Testing during installation. The browser download is approximately 170 MB on macOS, 282 MB on Linux and 280 MB on Windows according to Puppeteer’s installation documentation. Allow enough disk space and outbound network access. If your package manager disabled install scripts, fetch the browser explicitly:
Recommended Free Tools
npx puppeteer browsers installBy contrast, puppeteer-core does not download a browser. Choose it only when your environment already manages Chrome or Chromium, and plan to pass an explicit executable path or a browser channel.
Option 1: use a JavaScript kernel
A JavaScript kernel lets you place Puppeteer code directly in notebook cells. The exact kernel package and registration command vary by operating system and kernel project, so install a maintained Node.js kernel according to that project’s instructions, then select it from Jupyter’s Kernel menu. The important checks are that the kernel uses the same Node installation where you ran npm install puppeteer, and that its working directory can resolve the project’s node_modules.
Run a first browser cell
In a JavaScript notebook cell, use Puppeteer’s asynchronous launch, navigation and close sequence:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
const title = await page.title();
console.log(title);
await browser.close();The expected output is the page title, usually Example Domain. Keeping await browser.close() in the same cell prevents orphaned Chrome processes when you rerun cells.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Capture a screenshot or extract page data
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
await page.goto('https://example.com', { waitUntil: 'networkidle2', timeout: 60000 });
await page.screenshot({ path: 'example.png', fullPage: true });
const heading = await page.$eval('h1', el => el.textContent.trim());
console.log({ heading });
} finally {
await browser.close();
}Use domcontentloaded for a quick first render. Use networkidle2 only when waiting for late network activity is useful; analytics, advertisements and long-lived connections can prevent a page from becoming idle.
Rank #2
Headless modes
headless: trueis the normal unattended mode and displays no window.headless: falseopens a visible browser for local debugging.headless: 'shell'selects Puppeteer’s separate Chrome headless-shell mode.
Debug visibly on a desktop, then switch back to headless mode on notebook servers.
Option 2: keep the Python kernel and call Node
This approach avoids changing your notebook kernel. Put Puppeteer code in a JavaScript file beside the notebook, have it print machine-readable output, and invoke it from Python.
Create the Node script
// capture.mjs
import puppeteer from 'puppeteer';
const url = process.argv[2] || 'https://example.com';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
const result = {
url: page.url(),
title: await page.title()
};
console.log(JSON.stringify(result));
} finally {
await browser.close();
}Run it directly to verify Node can resolve Puppeteer:
node capture.mjs https://example.comInvoke it from a Python notebook cell
import json
import subprocess
completed = subprocess.run(
["node", "capture.mjs", "https://example.com"],
check=True,
capture_output=True,
text=True,
timeout=90,
)
result = json.loads(completed.stdout)
resultcheck=True turns a non-zero Node exit into a visible Python exception. For larger results, write a JSON file or use a temporary directory rather than placing binary screenshots on standard output.
Pass notebook data safely
For URLs supplied by users or a dataframe, pass them as separate subprocess arguments rather than concatenating a shell command. If you need many pages, keep one browser process alive in a Node worker and send it newline-delimited JSON; launching Chrome for every row is slower and consumes more memory.
Using an existing Chrome with puppeteer-core
Use this variant when a managed image already contains Chrome or Chromium:
npm install puppeteer-coreThen specify a binary path:
import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
headless: true,
executablePath: '/usr/bin/google-chrome'
});
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();The path above is an example, not a universal location. Discover the actual path in your image, or use Puppeteer’s channel option when a supported installed Chrome channel is available. Do not assume the browser version is compatible: an upgraded system browser can require a corresponding Puppeteer version.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Notebook-specific reliability practices
Make cleanup unconditional
Use try...finally around every browser session. Interrupting a cell can still leave a process behind, so periodically inspect and clean up abandoned browser processes in managed environments.
Control waits explicitly
Prefer a meaningful selector or application event over an arbitrary sleep:
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.waitForSelector('h1', { timeout: 15000 });For client-rendered applications, wait for the selector that proves the data is present. Set navigation and selector timeouts appropriate to your network rather than allowing a cell to hang indefinitely.
Keep artifacts outside notebook output
Save screenshots and PDFs to a known directory, then display or download them from a separate cell. This keeps notebook JSON smaller and makes reruns less likely to exhaust memory.
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 errorsPlan for hosted Linux
Containers and hosted notebooks may lack Chrome’s shared libraries, fonts, a usable sandbox or writable cache directories. Cloud runtimes do not necessarily include all packages required by Headless Chrome. Use a base image documented for Chrome, persist or configure Puppeteer’s cache, and verify file ownership for the notebook user.
Common errors and fixes
“Cannot find module ‘puppeteer’”
Cause: The JavaScript kernel or subprocess is using a different working directory or Node installation from the one where you ran npm install.
Fix: Print process.cwd() and process.execPath in the notebook, start Jupyter from the project directory, or use an absolute path to the script and project.
“Could not find Chrome”
Cause: Install scripts were blocked, the browser cache is missing, or the cache is not writable.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix: Run npx puppeteer browsers install, permit the package’s browser-install script, and check disk space and cache permissions.
Using puppeteer-core without an executable
Cause: puppeteer-core intentionally has no default browser.
Fix: Supply executablePath or channel, or install the full puppeteer package instead.
Linux sandbox or launch failure
Cause: Missing system packages, an unavailable sandbox, permissions, or an unwritable temporary directory.
Fix: Install the dependencies required by your image, run as a user that owns the cache and temporary directories, and verify sandbox support. Only for trusted content and environments where no usable sandbox exists should you consider --no-sandbox; it reduces isolation and is not a general fix.
The page loads forever or content is missing
Cause: A never-ending connection defeats an idle-network condition, or the application renders after the event you waited for.
Fix: Use a bounded navigation timeout, wait for a specific selector, and inspect the URL, console messages and response status. Avoid treating networkidle2 as proof that every widget has finished.
A visible browser cannot start
Cause: A server has no display.
Fix: Use headless mode on servers. Reserve headless:false for a desktop session with a display (or a deliberately configured virtual display).
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server, so a notebook can request an image without installing Chrome, a kernel extension or Linux browser packages. A single GET request returns PNG, JPEG, WebP or PDF. See the ScreenshotNeo API documentation for all parameters.
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython and Node.js calls use the same endpoint:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie and consent banners, newsletter popups and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed. Response headers identify the page verdict and whether it was billed.
- An MCP server provides
take_screenshot,get_page_infoandcapture_pdftools for Claude, Cursor and other MCP clients. - The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan.
Create a free ScreenshotNeo account to get the 1,000 monthly screenshots without adding a card.
FAQ
Can I install Puppeteer with pip?
No. Puppeteer is installed with npm because it is a Node.js library. Python can control it indirectly by launching a Node process.
Does installing Puppeteer always install Chrome?
The full puppeteer package normally downloads Chrome for Testing, but blocked install scripts or restricted networks can prevent that. puppeteer-core never downloads a browser.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Should notebook code run headful or headless?
Use headful mode to see a local browser while debugging. Use headless mode for unattended notebooks, servers and containers.
Can one browser serve many notebook cells?
Yes, but manage its lifetime explicitly and close it when the notebook session ends. A long-lived browser reduces launch overhead while increasing the impact of a leaked or crashed process.
Frequently Asked Questions
Can I install Puppeteer with pip?
No. Puppeteer is installed with npm because it is a Node.js library. Python can control it indirectly by launching a Node process.
Does installing Puppeteer always install Chrome?
The full puppeteer package normally downloads Chrome for Testing; puppeteer-core does not.
Should notebook code run headful or headless?
Use headful mode for local debugging and headless mode for unattended or server execution.
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.
