Install & Compatibility
Where this runs
tested against v0.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 0.000s · 174MB
173MB installed
● package 173MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
page
✓ def test_example(page):
✗ from pytest_playwright import page
pytest-playwright provides fixtures (like 'page') automatically; they are not imported directly from the package.
Page (for type hinting)
✓ from playwright.sync_api import Page
Used for type hinting the 'page' fixture, not to instantiate it.
This quickstart demonstrates a basic web test using the `page` fixture provided by pytest-playwright. It navigates to Google, asserts the title, and takes a screenshot.
import pytest
def test_example_is_working(page):
page.goto("https://www.google.com")
assert "Google" in page.title()
page.screenshot(path="screenshot.png")
# To run this test file:
# 1. Save as e.g., `test_my_app.py`
# 2. Ensure browsers are installed: `playwright install`
# 3. Run: `pytest test_my_app.py`
pytest --version
Debug
Known issues
gotchaPlaywright requires browser binaries to be installed separately. Tests will fail with 'Playwright was not installed. Please run `playwright install`' if browsers are missing.fixAfter installing `pytest-playwright`, run `playwright install` in your terminal to download browser binaries.
affects: All versions
gotchaBy default, `page`, `browser`, and `context` fixtures are created and torn down for *each* test function. While ensuring isolation, this can be slow for large test suites.fixTo improve performance, use pytest command-line options like `--browser-context-scope=session` or `--browser-scope=session` to share browser resources across tests. For custom fixtures, use `pytest.fixture(scope="session")`.
affects: All versions
gotchaPlaywright runs browsers in headless mode by default (no visible UI). This can make debugging visual issues difficult.fixRun tests with `--headless=false` (e.g., `pytest --headless=false`) to launch browsers with a visible UI during execution. For more fine-grained control, use the `browser_args` fixture.
affects: All versions
gotchapytest-playwright provides synchronous Playwright API fixtures (e.g., `page`, `browser`) by default. If your tests require `async`/`await` patterns, you must explicitly use the asynchronous fixtures (e.g., `apage`, `abrowser`).fixFor asynchronous tests, define your test function as `async def test_my_async(apage):` and use `await apage.goto(...)`.
affects: All versions
breakingpytest-playwright has strict version compatibility requirements with the `playwright` library. Installing incompatible versions can lead to runtime errors or unexpected behavior due to API mismatches.fixAlways check `pytest-playwright`'s `install_requires` for the compatible `playwright` version range (e.g., `playwright>=1.39.0`) and ensure both packages are upgraded together.
affects: All versions, especially across major/minor `playwright` releases.
Errors
Common errors & fixes
Fixture 'page' not found
The `pytest-playwright` plugin is not correctly installed or activated, or the test function does not explicitly request the 'page' fixture.
fixEnsure `pytest-playwright` is installed (`pip install pytest-playwright`) and that your test function accepts 'page' as an argument: `def test_example(page):`
playwright._impl._api_types.Error: Executable doesn't exist at ...
The browser binaries (e.g., Chromium, Firefox, WebKit) required by Playwright have not been downloaded and installed in your environment.
fixRun `playwright install` in your terminal to download and set up the necessary browser executables.
ModuleNotFoundError: No module named 'pytest_playwright'
The `pytest-playwright` plugin itself is not installed in your current Python environment.
fixInstall the plugin using pip: `pip install pytest-playwright`
ModuleNotFoundError: No module named 'playwright'
The core Playwright Python library, which `pytest-playwright` depends on, is not installed in the current Python environment.
fixInstall the Playwright library: `pip install playwright`
Upgrade
Version history
0.9.0latest on PyPI · released Aug 10, 2026
Audit
Dependencies
playwrightrequiredCore web automation library; pytest-playwright is a plugin for it.
pytestrequiredTesting framework; pytest-playwright is a plugin for it.