types-lxml

2026.2.16 · active · verified Fri Apr 10

types-lxml, version 2026.2.16, provides comprehensive external type annotations (stubs) for the `lxml` library, enabling static type checking with tools like MyPy and Pyright, and improving IDE support. It is actively maintained with frequent updates, often releasing multiple versions per month, and is a more complete fork of the original `lxml-stubs` project. It aims to cover major lxml submodules like `lxml.etree`, `lxml.html`, and `lxml.objectify` for Python 3.9 and newer.

Warnings

breaking Python 3.8 support was dropped since the 2025.11.25 release. Ensure your project uses Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or later.
gotcha Pyright is generally the preferred type checker for lxml code over MyPy. lxml's attribute normalization can be too restrictive for MyPy, leading to potential false positives or difficulties.
Fix: Consider using Pyright for type checking projects that heavily rely on lxml. If using MyPy, be aware of potential strictness around lxml's dynamic behaviors.
breaking Since the 2025.08.25 release, `types-lxml` officially supports `lxml` versions 6.0 and 5.4, and no longer tests against `lxml` 4.9.
Fix: Ensure your `lxml` dependency is updated to a supported version (e.g., 5.4 or 6.0+).
gotcha When using specific lxml types, particularly internal ones like `_Element` or `_ElementTree` in type annotations in your own code, it's best practice to import them from `lxml` directly, not `types_lxml`. Also, use `from __future__ import annotations` or quote the type hints to avoid forward reference issues.
Fix: Example: `from __future__ import annotations` then `from lxml.etree import _Element` or `def my_func(element: "_Element"): ...`.
gotcha Since the 2024.08.07 release, there are two versions of `types-lxml`: the default and `types-lxml-multi-subclass`. The latter is intended for specific needs involving the creation of multiple lxml element subclasses.
Fix: Most users should stick to the default `types-lxml`. Only install `types-lxml-multi-subclass` if you have specific advanced subclassing requirements for lxml elements.

Install

pip install types-lxml Install stable version

Imports

etree
```
from lxml import etree
```
types-lxml provides stubs for lxml; you import from lxml itself, and type checkers use the stubs.
html
```
from lxml import html
```
types-lxml provides stubs for lxml; you import from lxml itself, and type checkers use the stubs.

Quickstart

This quickstart demonstrates basic XML parsing, element finding, and modification using `lxml.etree`. `types-lxml` enhances this experience by providing accurate type hints for `lxml` objects like `_Element` and `_ElementTree`, which are consumed by static type checkers and IDEs.

from lxml import etree

# Example XML string
xml_string: str = '<root><item id="1">Apple</item><item id="2">Banana</item></root>'

# Parse the XML string
root: etree._Element = etree.fromstring(xml_string)

# Find an element by tag name
item: etree._Element | None = root.find('item')
if item is not None:
    print(f"First item: {item.text}")

# Find all elements with a specific tag
all_items: list[etree._Element] = root.findall('item')
for i, element in enumerate(all_items):
    item_id: str | None = element.get('id')
    print(f"Item {i+1} (ID: {item_id}): {element.text}")

# Create a new element and append it
new_element: etree._Element = etree.SubElement(root, 'item', id='3')
new_element.text = 'Cherry'

# Print the modified XML
print("\nModified XML:")
print(etree.tostring(root, pretty_print=True).decode())

view raw JSON →