Playwright

1.58.0 verified Tue May 12 auth: no python install: draft quickstart: stale

Microsoft's browser automation library for Python. Automates Chromium, Firefox, and WebKit. Current version is 1.58.0 (Jan 2026). Requires Python >=3.9. Critical two-step install: pip install playwright followed by playwright install to download browser binaries — omitting the second step causes BrowserType.launch: Executable doesn't exist error.

pip install playwright

Common errors

error BrowserType.launch: Executable doesn't exist at C:\Users\<user>\AppData\Local\ms-playwright\chromium-xxxx\chrome-win\chrome.exe ↓

cause This error occurs when the Playwright browser binaries have not been downloaded or are not found at the expected path, usually because the `playwright install` command was not run after `pip install playwright`, or there's a version mismatch.

fix

After installing the Python package (pip install playwright), you must also install the browser binaries by running playwright install in your terminal. For specific browsers, use playwright install chromium, playwright install firefox, or playwright install webkit.

error ModuleNotFoundError: No module named 'playwright' ↓

cause This error means the Playwright Python package is not installed in your current Python environment, or there's an issue with your Python path or a naming conflict (e.g., a local file named `playwright.py`).

fix

Install the Playwright Python package using pip install playwright. If it's already installed, ensure your Python environment is correctly activated and there isn't a file named playwright.py in your project directory that might be shadowing the actual library.

error playwright._impl._api_types.Error: TimeoutError: Timeout 30000ms exceeded. ↓

cause This generic timeout error indicates that a Playwright operation (like navigating, clicking, or waiting for a selector) took longer than the default 30-second timeout to complete.

fix

Increase the timeout for the specific action or globally. For an action, pass a timeout argument (e.g., page.goto('url', timeout=60000)). For waiting for a selector, use page.locator('#element').wait_for(timeout=10000). Avoid arbitrary time.sleep() calls and rely on Playwright's auto-waiting capabilities or explicit waits for conditions.

error page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:3000/ ↓

cause This error occurs when Playwright tries to navigate to a URL, but the browser cannot establish a connection to the specified address, often seen in CI/CD pipelines or when the target server (e.g., a local web server) is not running or accessible from the Playwright context.

fix

Ensure that the web server or application you are trying to access is running and accessible at the specified URL and port from within the environment where Playwright is executing. In CI environments, this often means properly setting up and waiting for a webServer in your Playwright configuration or ensuring service dependencies are met.

error locator.click: Target closed ↓

cause This error typically occurs when you attempt to interact with a Playwright object (like a `Page`, `Context`, or `ElementHandle`) after it has already been closed, disposed, or the underlying browser process has terminated prematurely. It's common in asynchronous code where `await` might be missing, or a loop doesn't complete its operations before the browser is closed.

fix

Ensure all asynchronous operations involving Playwright objects are awaited. Use with sync_playwright() as p: for synchronous API to ensure proper resource management. Avoid closing pages, contexts, or browsers until all intended interactions with them are complete. If iterating, use for...of loops with await for asynchronous operations inside the loop.

Warnings

breaking Browser binaries are NOT included in the pip package. After pip install playwright, you must run playwright install (or playwright install chromium) to download browsers. Omitting this raises: BrowserType.launch: Executable doesn't exist at [path]. ↓

fix Two-step install: pip install playwright then playwright install. In CI/Docker: playwright install --with-deps to also install OS-level dependencies.

breaking Python 3.8 support dropped in 1.51. Minimum is now Python 3.9. ↓

fix Pin playwright<1.51 for Python 3.8 environments.

breaking page.accessibility was removed in 1.57 after 3 years of deprecation. Code using page.accessibility raises AttributeError. ↓

fix Use a dedicated accessibility testing library like Axe. The Playwright docs link to Axe integration guides.

breaking Docker image mcr.microsoft.com/playwright no longer contains Python. Use mcr.microsoft.com/playwright/python for Python-based automation in Docker. ↓

fix Update Dockerfiles to use: FROM mcr.microsoft.com/playwright/python:v1.58.0-jammy

gotcha Mixing sync and async APIs causes cryptic errors. Using await on sync_playwright methods raises TypeError. Using sync methods inside async functions can deadlock. ↓

fix Pick one: from playwright.sync_api import sync_playwright for sync code, or from playwright.async_api import async_playwright for async code. Never import from the wrong module.

gotcha Locators are strongly preferred over raw CSS/XPath selectors. page.query_selector() and page.click('#some-id') work but are fragile. Locators (get_by_role, get_by_label, get_by_text) are auto-retrying and test-ID based. ↓

fix Replace page.click('#submit') with page.get_by_role('button', name='Submit').click(). Use page.get_by_label() for form inputs, page.get_by_test_id() for data-testid attributes.

gotcha playwright install downloads browsers to a version-specific cache path. Upgrading playwright without re-running playwright install uses stale binaries and may cause browser launch failures. ↓

fix After every pip install --upgrade playwright, run playwright install again.

breaking Playwright might not immediately release official wheels or provide full support for the very latest Python versions upon their release. If you are using a bleeding-edge Python version (e.g., Python 3.13+), 'pip install playwright' may fail with 'No matching distribution found' if compatible distributions are not yet available on PyPI for your specific environment (Python version, OS, architecture). ↓

fix To resolve this, consider using a slightly older, officially supported Python version (e.g., Python 3.12 or 3.11, depending on current Playwright release cycles). Alternatively, wait for Playwright to release compatible distributions for your Python version and platform. Always check Playwright's official documentation or PyPI page for supported Python versions and their compatible environments.

Install

playwright install

playwright install chromium

playwright install --with-deps

Install compatibility draft last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - 0.14s 154M

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - 0.29s 156M

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - 0.50s 148M

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - 0.53s 147M

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - 0.17s 153M

Imports

sync_playwright

wrong

import playwright  # ImportError — must import from submodule
from playwright import sync_playwright  # ImportError — wrong path

correct

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('https://example.com')
    print(page.title())
    browser.close()

Import from playwright.sync_api or playwright.async_api — not from playwright directly. The correct sync import is from playwright.sync_api import sync_playwright.

async_playwright

wrong

from playwright.sync_api import async_playwright  # ImportError — async is in async_api

correct

import asyncio
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto('https://example.com')
        await browser.close()

asyncio.run(main())

Sync API: from playwright.sync_api import sync_playwright. Async API: from playwright.async_api import async_playwright. Never mix sync and async — calling await on sync methods raises TypeError.

Quickstart stale last tested: 2026-04-23

Basic sync pattern. Use locators (get_by_role, get_by_label) not raw CSS selectors.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Launch browser
    browser = p.chromium.launch(headless=True)
    context = browser.new_context()
    page = context.new_page()
    
    # Navigate and interact
    page.goto('https://example.com')
    print('Title:', page.title())
    
    # Use locators (preferred over selectors)
    page.get_by_role('button', name='Submit').click()
    page.get_by_label('Email').fill('user@example.com')
    
    # Wait for navigation
    page.wait_for_load_state('networkidle')
    
    # Screenshot
    page.screenshot(path='screenshot.png')
    browser.close()