Skip to content

Finding elements with XPath selectors in Playwright

XPath lets you target a page element through its tag, position, attributes, or relationship to nearby elements.

OUTPUT FORMATSHTMLJSONMarkdown

In Playwright Python, you hand that expression to page.locator() and then work with the locator it returns.

Set up and read an element by tag

Install Playwright together with its browser binaries before running any script; the protected setup module code0001 contains the exact commands. The workflow then has four steps: launch a browser, open the target page, create a locator from an XPath expression, and act on that locator. A locator is not the element itself — it is a reusable handle that Playwright resolves against the live page when you read text, click, or fill a field. That separation is why the same locator pattern works for both reading a title and interacting with a form control.

Install the library and browser binaries before running the Python examples.

pip install playwright
playwright install

A complete reading example

The protected example module code0002 opens a page, locates its title element with XPath, prints the text, and closes the browser. The key line is the locator call: page.locator() receives an XPath expression and returns a locator whose text_content() gives the element's text. The output shown in image0002 is simply the current title text of the example homepage, which confirms the locator resolved to the right element.

Set TARGET_URL to the page you want to inspect. This example opens a page, locates its title and closes the browser.

import os
from playwright.sync_api import sync_playwright

with sync_playwright() as engine:
    browser = engine.chromium.launch(headless=True)
    tab = browser.new_page()
    tab.goto(os.environ["TARGET_URL"], wait_until="domcontentloaded")
    match = tab.locator("xpath=//title")
    print(match.text_content())
    browser.close()

Two accepted spellings for the same selector

Two spellings are accepted. The explicit form, shown in protected module code0003, prefixes the expression with xpath= so the selector type is visible at a glance. The shorter form, shown in protected module code0004, relies on the leading // to signal XPath. Both are detected as XPath by Playwright, so the choice is a readability decision rather than a functional one — prefer the explicit prefix in shared code, and use the short form when brevity matters in a quick script.

Matching by attribute and handling duplicates

Tag-only selectors break when a page repeats an element, so attribute matching is the next step. Protected module code0005 matches anchor elements whose href contains /pricing and then takes .first, because the example page links to that destination more than once. The printed result in image0003 is the text of that first matching link. Use this pattern whenever a selector could match several nodes: narrow it with an attribute first, then decide explicitly which match to use instead of letting an ambiguous locator fail later.

Use a target page containing a pricing link for this attribute-matching example. The first matching anchor is selected if more than one exists.

import os
from playwright.sync_api import sync_playwright

with sync_playwright() as engine:
    browser = engine.chromium.launch(headless=True)
    tab = browser.new_page()
    tab.goto(os.environ["TARGET_URL"], wait_until="domcontentloaded")
    match = tab.locator("xpath=//a[contains(@href, '/pricing')]").first
    print(match.text_content())
    browser.close()

Quick checklist before you run a locator

Before you run a locator, check that Playwright and its browsers are installed, that the page has finished loading enough for the element to exist, and that your expression starts with // or carries the xpath= prefix. After creating the locator, confirm whether it could match more than one element; if so, add .first or narrow the expression with an attribute. Finally, verify the printed or acted-on text matches the element you intended, as the two worked examples demonstrate.

Choosing between the two XPath spellings
FormHow Playwright recognises itWhen to prefer it
xpath=//titleExplicit xpath= prefixShared or long-lived code where the selector type should be obvious
//titleLeading //Short scripts where brevity matters

Both forms are detected as XPath; the difference is readability only.

From tag matching to attribute matching
SituationSelector approachDuplicate handling
Element identified by tag onlyTag-based XPath such as //titleNot needed when the tag is unique
Element identified by attributeAttribute condition such as contains(@href, '/pricing')Add .first when the same link appears more than once

Attribute example is tied to the worked pricing-link case; adapt the attribute value to your own page.

Frequently asked questions

How do I use XPath with page.locator() in Playwright?

Pass the selector to page.locator(), either with the xpath= prefix or by starting it with //, then use the returned locator to read text, click, or fill a field.

Do I need the xpath= prefix?

Playwright treats both forms as XPath. Keeping xpath= in the code makes the selector type clearer when someone else reads it later.

How do I handle several elements matching the same XPath?

Use an attribute-based XPath such as one matching an anchor whose href contains /pricing, and add .first when the same link appears more than once so you act on the first match.