Finding elements with XPath selectors in Playwright
XPath lets you target a page element through its tag, position, attributes, or relationship to nearby elements.
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 installA 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.
| Form | How Playwright recognises it | When to prefer it |
|---|---|---|
| xpath=//title | Explicit xpath= prefix | Shared or long-lived code where the selector type should be obvious |
| //title | Leading // | Short scripts where brevity matters |
Both forms are detected as XPath; the difference is readability only.
| Situation | Selector approach | Duplicate handling |
|---|---|---|
| Element identified by tag only | Tag-based XPath such as //title | Not needed when the tag is unique |
| Element identified by attribute | Attribute 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.