Playwright

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.

Install

• pip install playwright Step 1: Install Python package
• playwright install Step 2: Download browser binaries (REQUIRED)
• playwright install chromium Step 2 (minimal): Chromium only
• playwright install --with-deps Step 2 (CI/Linux): Install browsers + OS dependencies

Imports

• sync_playwright

  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

  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

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()