Skip to content

How to run Playwright in Jupyter notebooks?

Jupyter notebooks already run on an asyncio event loop, so Playwright must be used through its asynchronous interface there.

OUTPUT FORMATSHTMLJSONMarkdown

The practical pattern is to await starting Playwright, launching a browser, creating a page, and navigating to a URL.

Use the async interface

Choose the async interface from the start. Import the asynchronous entry point, then await each Playwright call in sequence. This keeps notebook execution aligned with the event loop instead of trying to run a separate blocking Playwright flow inside it.

Minimal sequence

A minimal working sequence has four stages. First, start Playwright asynchronously. Second, launch Chromium, using headed mode when you want to watch the browser. Third, create a new page from that browser. Fourth, navigate that page to the destination address and await completion. If any stage is not awaited, later stages can run before the browser or page is ready.

Quick troubleshooting checklist

Before running the sequence, check that you imported the async entry point rather than the synchronous one, that every Playwright operation is awaited, and that the page is created before navigation. A common failure is mixing synchronous calls into an otherwise async notebook cell, which breaks the expected event-loop pattern.

Notebook execution sequence
StageWhat to awaitPurpose
StartPlaywright startupInitialise the Playwright driver
LaunchChromium launchOpen a browser instance, headed in the example
PageNew page creationProvide a page to navigate
NavigatePage navigationLoad the target address

Sequence derived from the protected example module; exact code is retained privately.

Frequently asked questions

Why does Playwright need its async API in a notebook?

Use the asynchronous Playwright interface and await each operation. That matches the event-loop model Jupyter already uses, whereas the synchronous interface is intended for scripts that manage their own blocking flow.

What does the minimal notebook example do?

Start Playwright, launch Chromium, create a page, and navigate to the target address. In the example pattern, Chromium is launched in headed mode by setting headless to False.