XPath-syntaxis-spiekbriefje
XPath-syntaxis-spiekbriefje
XPath navigates an XML or HTML document as a tree. Every step has the form axis::node-test[predicate], and most of it has a short form: //div[@class="card"]/a/@href reads โthe href of every a inside any div with class cardโ.
โ ๏ธ Browsers, Selenium and most scrapers implement XPath 1.0.
ends-with(),matches(),lower-case()andreplace()are 2.0+ and only work in tools likexmllint, Saxon orlxmlwith an XSLT 2.0 processor. Workarounds for 1.0 are given below.
๐งญ Path Syntax
| XPath | Selects |
|---|---|
/ | From the document root โ an absolute path |
// | Anywhere in the document, at any depth |
. | The current (context) node |
.. | The parent of the context node |
@attr | An attribute |
* | Any element |
@* | Any attribute |
text() | The text nodes of an element |
node() | Any node at all, text and comments included |
[n] | The nth match โ 1-based, not 0-based |
[last()] | The last match |
a | b | The union of two expressions |
/html/body (: absolute: the body of the page :)
//text() (: every text node :)
./div/b (: relative to the context node :)
(//p)[2] (: the second p in the whole document :)
//p[2] (: every p that is the second p of its parent :)
๐ท Elements & Attributes
| XPath | Description | CSS |
|---|---|---|
//E | Every <E> element | E |
(//E)[2] | The second <E> in the document | โ |
//E[@A] | <E> carrying attribute A | E[A] |
//E[@A="t"] | <E> where A is exactly t | E[A='t'] |
//E[contains(@A,"t")] | <E> where A contains t | E[A*='t'] |
//E[starts-with(@A,"t")] | <E> where A starts with t | E[A^='t'] |
//E[substring(@A, string-length(@A)-2)="t"] | <E> where A ends with t (1.0 trick) | E[A$='t'] |
//E[ends-with(@A,"t")] | The same, XPath 2.0+ only | E[A$='t'] |
//E[matches(@A,"r")] | A matches regex r (2.0+) | โ |
//E/@A | The value of attribute A | โ |
//*/@A | Attribute A of any element | โ |
//E[@A2="t"]/@A1 | A1 where A2 is t | โ |
//E1[@id="I1"] | //E2[@id="I2"] | Either element | E1#I1, E2#I2 |
//E[@id="I1" or @id="I2"] | <E> with either id | E#I1, E#I2 |
๐ Id, Name, Class & Language
| XPath | Description | CSS |
|---|---|---|
//*[@id="I"] | The element with id I | #I |
//E[@id="I"] | <E> with id I | E#I |
//*[@name="N"] | Any element named N | [name='N'] |
//*[@name="N"][@value="v"] | Named N with value v | [name='N'][value='v'] |
//*[contains(concat(" ", normalize-space(@class), " "), " C ")] | Element with class C โ the padding avoids matching C2 | .C |
//E[contains(concat(" ", normalize-space(@class), " "), " C ")] | <E> with class C | E.C |
//E[@lang="L" or starts-with(@lang, concat("L","-"))] | <E> in language L or a subcode | E[lang|='L'] |
๐ Text & Links
| XPath | Description | CSS |
|---|---|---|
//*[.="t"] | Element whose whole text is exactly t | โ |
//E[contains(text(),"t")] | <E> with a text node containing t | โ |
//E[contains(.,"t")] | <E> whose text, descendants included, contains t | โ |
//E[normalize-space()="t"] | Exact text, ignoring surrounding whitespace | โ |
//a | Every link | a |
//a[.="t"] | The link labelled exactly t | โ |
//a[@href="url"] | The link pointing at url | a[href='url'] |
//a[.="t"]/@href | The URL behind the label t | โ |
//a[starts-with(@href,"https")] | Secure links only | a[href^='https'] |
๐ช Parents & Children
| XPath | Description | CSS |
|---|---|---|
//E/*[1] | First child of <E> | E > *:first-child |
//E/*[last()] | Last child of <E> | E > *:last-child |
//E[1] | Each <E> that is the first of its type in its parent | E:first-of-type |
//E[last()] | Last <E> of its type | E:last-of-type |
//E[2] | Second <E> of its type | E:nth-of-type(2) |
//*[2][name()="E"] | Second child, if it is an <E> | E:nth-child(2) |
//E[last()-1] | Second-to-last <E> of its type | E:nth-last-of-type(2) |
//E/.. | The parent of <E> | โ |
//div/form/parent::* | Every element that has a form child | div:has(> form) |
//*[@id="I"]//E | <E> anywhere under id I | #I E |
//E[count(*)=0] | <E> with no element children | E:empty |
//E[count(*)=1] | <E> with exactly one child | โ |
//E[count(preceding-sibling::*)+count(following-sibling::*)=0] | <E> that is an only child | E:only-child |
//E[count(../E)=1] | <E> with no <E> siblings | E:only-of-type |
//E1[E2 and not(*[not(self::E2)])] | <E1> whose only children are <E2> | โ |
//E[position() mod N = M + 1] | Every Nth element, offset by M | E:nth-child(Nn+M) |
๐ฅ Siblings
| XPath | Description | CSS |
|---|---|---|
//E2/following-sibling::E1 | Every <E1> after a sibling <E2> | E2 ~ E1 |
//E2/following-sibling::*[1][name()="E1"] | <E1> immediately after <E2> | E2 + E1 |
//E2/following-sibling::*[2][name()="E1"] | <E1> two siblings after <E2> | E2 + * + E1 |
//E/following-sibling::*[1] | Whatever follows <E> directly | E + * |
//E2/preceding-sibling::E1 | Every <E1> before a sibling <E2> | โ |
//E2/preceding-sibling::*[1][name()="E1"] | <E1> immediately before <E2> | โ |
//E/preceding-sibling::*[1] | Whatever precedes <E> directly | โ |
๐ Tables & Form State
| XPath | Description | CSS |
|---|---|---|
//*[@id="T"]//tr[3]//td[2] | Third row, second cell | #T tr:nth-child(3) td:nth-child(2) |
//td[preceding-sibling::td="t"] | The cell right after the one reading t | โ |
//td[preceding-sibling::td[contains(.,"t")]] | Cells following one containing t | td:has(~ td) |
//table[count(tr)=1 and count(tr/td)=2] | Tables with one row and two columns | โ |
//table/tr[last()] | The last row of a table | table tr:last-child |
//E[@disabled] | A disabled control | E:disabled |
//E[not(@disabled)] | A control that is not disabled | E:enabled |
//*[@checked] | A checked checkbox or radio | :checked |
๐งฎ Functions
Strings
| Function | Returns |
|---|---|
contains(haystack, needle) | True when the first string contains the second |
starts-with(haystack, needle) | True when it starts with it |
concat(s1, s2, โฆ) | The strings joined together |
normalize-space(s) | The string with runs of whitespace collapsed and trimmed |
string-length(s) | The number of characters |
substring(s, start [, length]) | A slice โ 1-based |
substring-before(haystack, needle) | Everything before the first occurrence |
substring-after(haystack, needle) | Everything after it |
translate(s, from, to) | Characters mapped one by one โ the 1.0 way to fold case |
Numbers, logic & nodes
| Function | Returns |
|---|---|
count(node-set) | How many nodes matched |
sum(node-set) | The sum of their numeric values |
position() | The index of the context node within its step |
last() | The size of the context โ so [last()] is the final node |
name([node-set]) | The qualified name of the first node |
namespace-uri([node-set]) | Its namespace URI |
lang(s) | True when the node is in that language |
not(expr) | The negation |
true() / false() | Boolean constants |
boolean(expr) / string(o) / number(o) | Type conversions |
ceiling(n) / floor(n) / round(n) | Rounding |
๐ก Case-insensitive matching in XPath 1.0:
//E[contains(translate(@A,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz"), "t")]
๐งญ Axes
| Axis | Short form | Selects |
|---|---|---|
child | (default) | The direct children of the context node |
descendant | // | Every node below the context node |
descendant-or-self | // | The context node and everything below it |
parent | .. | The single parent node |
ancestor | โ | Parent, grandparent, up to the root |
ancestor-or-self | โ | The same, including the context node |
following | โ | Everything after the node in document order, except descendants |
following-sibling | โ | Later siblings under the same parent |
preceding | โ | Everything before it, except its ancestors |
preceding-sibling | โ | Earlier siblings under the same parent |
attribute | @ | The attributes of the node |
self | . | The context node itself |
//td[.="Total"]/ancestor::table (: the table a cell belongs to :)
//h2[.="Specs"]/following-sibling::ul[1] (: the list after a heading :)
//input[@name="q"]/ancestor-or-self::form (: the form wrapping a field :)
๐ง Worked Examples
//hr[@class="edge" and position()=1]
(: the first hr of class 'edge' under each parent :)
//table[parent::div[@class="pad"] and not(@id)]//a
(: links in unnamed tables inside a padded div :)
/html/body/div/*[preceding-sibling::h4]
(: whatever comes after an h4 :)
//tr/td[font[@class="head" and text()="TRACK"]]
(: cells whose font child says TRACK :)
//*[count(*)=3]
(: elements with exactly three children :)
//rdf:Seq/rdf:li/em:id
(: namespaced elements โ the prefixes must be bound by the host tool :)
//var | //acronym
(: a union of two node sets :)
๐ Running XPath
// browser devtools console
$x('//a[contains(@href, "docs")]');
// plain DOM API
document.evaluate('//h1', document, null, XPathResult.ANY_TYPE, null).iterateNext();
# from the shell, over XML or HTML
xmllint --xpath '//book/title/text()' catalog.xml
xmllint --html --xpath '//a/@href' page.html 2>/dev/null
from lxml import html
tree = html.parse('page.html')
tree.xpath('//div[@class="card"]/a/@href')
# Selenium and Playwright both accept XPath locators
driver.find_element(By.XPATH, '//button[normalize-space()="Save"]')
page.locator('xpath=//button[normalize-space()="Save"]').click()
โ ๏ธ Notes
- Indexes start at 1.
[0]never matches anything. //E[1]is per-parent,(//E)[1]is document-wide โ the single most common XPath bug.- Namespaced documents need prefixes registered with the host library; in XPath 1.0 a common workaround is
//*[local-name()="title"]. //is expensive on large documents; anchor the path when you can.- Prefer text matching with
normalize-space()โ HTML is full of stray whitespace and line breaks.
๐ Resources
Credit to the original author: https://gist.github.com/jmaccabee/550a0b9fcfdc7e6b170cd34c6ec7bc56