Typing Stubs for BeautifulSoup4

4.12.0.20250516 · active · verified Thu Apr 09

types-beautifulsoup4 provides PEP 561 compliant type stubs for the beautifulsoup4 library, enabling static type checkers like MyPy, Pyright, and PyCharm to analyze code using BeautifulSoup4 for type correctness. This package specifically targets beautifulsoup4 versions up to 4.12.*. It is part of the typeshed project, which automatically releases updates to stub packages on PyPI, often in sync with the upstream library's releases or typeshed's internal machinery.

Warnings

breaking Starting with `beautifulsoup4` version 4.13.0, the `beautifulsoup4` package itself includes type annotations. If you are using `beautifulsoup4` 4.13.0 or newer, you MUST uninstall `types-beautifulsoup4` to avoid potential conflicts or incorrect type checking behavior.
Fix: pip uninstall types-beautifulsoup4
gotcha Installing `types-beautifulsoup4` alone is not sufficient to run your code; you still need to install the `beautifulsoup4` runtime library. The `types-*` packages provide only type definitions, not the actual implementation.
Fix: Ensure `beautifulsoup4` is installed alongside `types-beautifulsoup4` (e.g., `pip install beautifulsoup4 types-beautifulsoup4`).
gotcha Type checkers may report `Any` types or incorrect type inference if there's a version mismatch between the installed `types-beautifulsoup4` package and your `beautifulsoup4` runtime library, or if the stub package is marked as 'partial'. This can lead to a loss of type checking precision.
Fix: Pin your `types-beautifulsoup4` version to match the major.minor version of `beautifulsoup4` (e.g., `types-beautifulsoup4==4.12.*` for `beautifulsoup4==4.12.*`). Also, be aware that some stubs are partial and may not cover all APIs.
gotcha Typeshed, the source for `types-beautifulsoup4`, sometimes introduces stricter type annotations or changes that, while technically correct, might cause your existing code to fail type checking. This can happen even with minor updates to the stub package.
Fix: Consider pinning your stub package versions (e.g., `types-beautifulsoup4==4.12.0.20250516`) in your `requirements.txt` to control when updates are applied, or review typeshed's changelog regularly.
gotcha Methods like `find()` and `find_all()` often return `None` if no matching element is found. Type checkers will correctly flag potential `None` access errors. Be explicit about handling optional return types in your code.
Fix: Use type guards (`if element is not None:`) or `Optional` / `Union[..., None]` in your type annotations to explicitly handle cases where an element might not be found.

Install

pip install types-beautifulsoup4 Install stub package

Imports

BeautifulSoup
```
from bs4 import BeautifulSoup
```
You import the types implicitly by having `types-beautifulsoup4` installed. You should never import directly from the `types-beautifulsoup4` package itself.
Tag
```
from bs4.element import Tag
```
Type stubs are automatically applied by type checkers when importing symbols from the `bs4` package.

Quickstart

This quickstart demonstrates how to use `beautifulsoup4` with type hints. With `types-beautifulsoup4` installed, a type checker will correctly infer the types of `soup`, `title_tag`, and `paragraph_tag` objects, enabling better autocompletion and error detection. Note the use of `| None` for `find()` results, as elements might not be present.

from bs4 import BeautifulSoup, Tag

html_doc: str = """
<html>
<head><title>The Title</title></head>
<body>
<p class="story">Hello World</p>
</body>
</html>
"""

soup: BeautifulSoup = BeautifulSoup(html_doc, 'html.parser')

# Accessing a tag with type hint
title_tag: Tag | None = soup.find('title')
if title_tag:
    print(f"Title: {title_tag.text}")

# Accessing a paragraph with type hint
paragraph_tag: Tag | None = soup.find('p', class_='story')
if paragraph_tag:
    print(f"Paragraph: {paragraph_tag.text}")

view raw JSON →