How to Run Playwright in Jupyter Notebooks
Install Playwright in your notebook kernel, use top-level await, fix browser and event-loop errors, and automate pages reliably with complete examples.

Playwright works well in Jupyter when you install both its Python package and a compatible browser, then use the asynchronous API with top-level await. The key notebook difference is that IPykernel already runs an asyncio event loop, so asyncio.run() is usually the wrong pattern inside a cell.
This guide shows the complete setup, a reusable notebook workflow, browser and context options, screenshots and PDFs, troubleshooting, and ways to make long-running notebook sessions reliable.
1. Install Playwright in the active Jupyter kernel
Start by installing the package into the same Python environment used by the notebook kernel. The %pip magic is useful because it asks the active IPython kernel where to install the package.
%pip install playwright
Playwright’s Python package and browser binaries are separate. Install Chromium (the simplest default for an introductory notebook) in a second cell:
!python -m playwright install chromium
The official Playwright documentation describes pip install playwright followed by playwright install. Installing an individual browser is supported, so use chromium, firefox, or webkit when you know which engine you need. On Linux, the host may also need operating-system libraries:
!python -m playwright install --with-deps chromium
Use --with-deps only when your notebook environment permits system package installation. Hosted services can restrict that operation; in that case, follow the provider’s image or container instructions. Playwright documents browser installation, version matching, and dependencies in its browser guide.
Confirm the kernel and package
import sys
print(sys.executable)
import playwright
print(playwright.__file__)
If the import fails after installation, the notebook is probably attached to a different environment than the one used by your terminal. Select the intended kernel, run the %pip command again, and restart the kernel if the environment changed.
2. Use top-level await instead of asyncio.run
IPython supports asynchronous statements directly in notebook cells. IPython’s autoawait documentation states that, in a notebook with ipykernel, the asyncio event loop is already running. Calling asyncio.run() attempts to create and manage another loop and commonly raises RuntimeError: asyncio.run() cannot be called from a running event loop.

Use Playwright’s async API directly:
from playwright.async_api import async_playwright
async with async_playwright() as p:
browser = await p.chromium.launch()
page = await browser.new_page()
await page.goto("https://example.com", wait_until="domcontentloaded")
print(await page.title())
await browser.close()
The context manager starts and stops Playwright, and closing the browser releases the browser process. This pattern is appropriate for a quick one-cell experiment.
A reusable browser helper
For several cells, keep one browser open and create isolated contexts or pages as needed. A browser context separates cookies, local storage, permissions, and cache from other contexts.
from playwright.async_api import async_playwright
pw = await async_playwright().start()
browser = await pw.chromium.launch(headless=True)
context = await browser.new_context(
viewport={"width": 1440, "height": 900},
device_scale_factor=1,
)
page = await context.new_page()
await page.goto("https://example.com", wait_until="networkidle")
print(await page.title())
await context.close()
await browser.close()
await pw.stop()
When you finish the notebook, run the cleanup cells even if you plan to execute more work later. Accumulated browser processes consume memory and file descriptors. A context manager is safer for a self-contained task:
async with async_playwright() as p:
browser = await p.chromium.launch()
try:
page = await browser.new_page()
await page.goto("https://example.com")
print(await page.title())
finally:
await browser.close()
3. Navigate, inspect, and interact
page.goto waits for a navigation event. Choose the wait condition according to the page rather than always waiting for every network request:
commit: the response has started loading.domcontentloaded: the initial HTML has been parsed.load: subresources such as images have loaded according to the page’s load event.networkidle: there are no network connections for a short period; analytics, polling, and advertisements can prevent this from becoming useful.
await page.goto("https://example.com", wait_until="domcontentloaded", timeout=60_000)
print("URL:", page.url)
print("Title:", await page.title())
print((await page.locator("body").inner_text())[:500])
Prefer locators over brittle timing and CSS chains. Locators automatically wait for actionable states:
heading = page.get_by_role("heading", name="Example Domain")
await heading.wait_for()
print(await heading.inner_text())
link = page.get_by_role("link", name="More information...")
await link.click()
await page.wait_for_load_state("domcontentloaded")
For a selector that may appear after a client-side request, wait for that selector explicitly:
await page.wait_for_selector("[data-testid='results']", state="visible", timeout=30_000)
count = await page.locator("[data-testid='results'] article").count()
print(count)
4. Capture screenshots and PDFs
Playwright can capture the visible viewport or the full page. The full-page option scrolls through the page so content outside the initial viewport can be included.
await page.screenshot(path="viewport.png")
await page.screenshot(path="full-page.png", full_page=True)
await page.screenshot(
path="retina.webp",
type="webp",
quality=85,
full_page=True,
)
To capture one element, locate it first and call screenshot on the locator:
card = page.locator(".pricing-card").first
await card.screenshot(path="pricing-card.png")
For a PDF, use Chromium’s PDF support. PDFs require a Chromium browser and work best when you set print-color adjustment on the page when color fidelity matters.
await page.emulate_media(media="print")
await page.pdf(
path="page.pdf",
format="A4",
print_background=True,
margin={"top": "16mm", "right": "16mm", "bottom": "16mm", "left": "16mm"},
)
To make screenshots deterministic, set the viewport, device scale factor, locale, timezone, and color scheme when creating the context:
context = await browser.new_context(
viewport={"width": 1280, "height": 800},
device_scale_factor=2,
color_scheme="dark",
locale="en-US",
timezone_id="America/New_York",
)
page = await context.new_page()
5. Notebook patterns for dynamic pages
Wait for application state
A fixed delay is sometimes useful for a known animation, but it should not replace a condition. Playwright’s guide warns that blocking time.sleep() can leave asynchronous operations in an outdated state. Use locator waits, assertions, or Playwright’s own timeout helper:
await page.locator("button.submit").click()
await page.locator(".success-message").wait_for(state="visible")
# A deliberate short delay, only when the page has no observable condition:
await page.wait_for_timeout(500)
Run JavaScript and add CSS
await page.add_style_tag(content="""
.cookie-banner, .newsletter-modal { display: none !important; }
""")
result = await page.evaluate("""() => ({
width: document.documentElement.scrollWidth,
height: document.documentElement.scrollHeight,
})""")
print(result)
Use page.evaluate for page-side inspection, not as a substitute for locator actions. Code in the page runs with the page’s permissions and origin, so treat values returned from an untrusted site as untrusted data.
Load lazy content before a full-page capture
Some sites load images only after an element approaches the viewport. Scroll gradually, then wait for images to finish:
await page.evaluate("""async () => {
await new Promise(resolve => {
let y = 0;
const step = 600;
const timer = setInterval(() => {
window.scrollBy(0, step);
y += step;
if (y >= document.body.scrollHeight) {
clearInterval(timer);
resolve();
}
}, 100);
});
}""")
await page.wait_for_timeout(1000)
await page.screenshot(path="loaded-page.png", full_page=True)
This is site-dependent: a page may use an intersection observer, an API call, or a framework-specific loading state. If possible, wait for the page’s actual content locator instead.
6. Browser choices and visible mode
Playwright supports Chromium, Firefox, and WebKit. Install the browser you intend to launch:
!python -m playwright install firefox
!python -m playwright install webkit
async with async_playwright() as p:
browser = await p.firefox.launch()
page = await browser.new_page()
await page.goto("https://example.com")
print(await page.title())
await browser.close()
Headless mode is the default and works in most notebook servers. To request a visible window locally:
browser = await p.chromium.launch(headless=False)
Headed mode requires a usable display. Hosted notebooks often run without one or prevent installation of graphical libraries, so use headless mode there. On Windows, Playwright’s Python documentation notes that its driver subprocess requires asyncio’s ProactorEventLoop; Python 3.8 and later use that loop by default. Avoid replacing the notebook’s event loop manually unless your environment specifically requires it.
7. A complete notebook example
The following cells create a browser, navigate to a page, inspect it, interact with a link, and save both image and PDF output.
from pathlib import Path
from playwright.async_api import async_playwright, TimeoutError as PlaywrightTimeoutError
output = Path("artifacts")
output.mkdir(exist_ok=True)
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
context = await browser.new_context(
viewport={"width": 1365, "height": 900},
device_scale_factor=1,
)
page = await context.new_page()
page.set_default_timeout(30_000)
try:
response = await page.goto(
"https://example.com",
wait_until="domcontentloaded",
timeout=60_000,
)
if response is None:
raise RuntimeError("The page did not return a navigation response")
print(response.status, await page.title())
await page.screenshot(path=str(output / "example.png"), full_page=True)
await page.emulate_media(media="print")
await page.pdf(path=str(output / "example.pdf"), format="A4")
except PlaywrightTimeoutError as exc:
print("Timed out:", exc)
finally:
await context.close()
await browser.close()
8. Troubleshooting checklist
| Error or symptom | Cause | Fix |
|---|---|---|
asyncio.run() cannot be called from a running event loop |
IPykernel already owns an asyncio loop. | Use top-level await and async with async_playwright(). Check %autoawait if async syntax is not accepted. |
Executable doesn't exist or browser launch failure |
The Python package is installed but its browser binary is missing. | Run !python -m playwright install chromium for the browser you launch. |
| Import succeeds in a terminal but fails in the notebook | Package installation went to another Python environment. | Print sys.executable, install with %pip in the active kernel, then restart it. |
| Linux launch reports missing shared libraries | The host image lacks browser system dependencies. | Try python -m playwright install --with-deps chromium where permitted, or use an image supplied by the notebook host. |
| Headed mode shows no window | The notebook server has no display or blocks GUI access. | Use the default headless mode, or configure a supported display on a local machine. |
| Navigation times out | The site is slow, keeps connections open, redirects, or blocks automation. | Use an appropriate wait_until, increase the navigation timeout, inspect redirects and response status, and wait for a specific locator instead of networkidle. |
| Element is not found | It is rendered later, inside an iframe, or the selector is unstable. | Wait for a locator, inspect the DOM, and use page.frame_locator(...) for an iframe. |
| Screenshot misses content | Content is lazy-loaded or an overlay covers it. | Scroll to trigger loading, wait for content, hide or dismiss overlays, then capture. |
| Results change between runs | Animations, time, locale, cookies, network data, or responsive layout differ. | Fix viewport, timezone, locale, color scheme, and test data; disable animations with injected CSS where appropriate. |
| Old browser behaves differently after an upgrade | Browser binaries track Playwright releases. | Re-run the browser install command after upgrading Playwright. |
9. Performance, reliability, and cost considerations
Launching a browser is relatively expensive compared with opening a page. For a notebook batch, launch Playwright and the browser once, then reuse the browser while creating a fresh context per task. Reuse a context only when sharing cookies and storage is intentional. Close pages and contexts that are no longer needed.
Choose the narrowest wait that represents success. domcontentloaded is often faster and more predictable than networkidle on pages with analytics or polling. Set explicit navigation and action timeouts so a stalled page does not keep a cell running indefinitely. Capture response status and log the final URL when diagnosing failures.
Parallel pages can improve throughput, but each page consumes memory and CPU. Start with a small number of pages, watch the notebook host’s limits, and reduce concurrency when Chromium is killed or the kernel becomes unstable. For repeatable output, pin the Playwright version in a requirements file and reinstall matching browser binaries after upgrades.
Playwright itself does not charge per screenshot; your costs are the notebook compute, storage, and any external services your page uses. Hosted notebook runtimes can stop or reset, so save artifacts to durable storage when the results matter.
10. Or skip the browser setup
If your goal is a clean website image or PDF rather than browser automation, ScreenshotNeo provides a single API request. Its capture service accepts a URL and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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 banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and whether it was billed. ScreenshotNeo also provides an MCP server so Claude, Cursor, and other MCP clients can call take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
11. Frequently asked questions
Can I use synchronous Playwright in Jupyter?
Playwright offers synchronous and asynchronous Python APIs, but the async API fits the notebook’s already-running event loop. Use the synchronous API in a separate script or process when that better matches your application.
Which browser should I install first?
Chromium is a practical default because it has a direct install command and supports the screenshot and PDF examples here. Install Firefox or WebKit when cross-engine behavior is part of your task.
Why does networkidle never happen?
Analytics, WebSockets, polling, and advertisements can keep requests active. Wait for the specific element or application state that means the page is ready.
How do I keep cookies between cells?
Keep the same browser context alive and create new pages inside it. Close the context when you want to discard its cookies and storage.
Can a hosted notebook display a browser window?
Only when the host provides a usable graphical display and permits the required libraries. Headless mode is the portable default.
What should I do after upgrading Playwright?
Install the matching browser binaries again, then restart the kernel. This prevents the Python package and executable versions from drifting apart.


