Install & Compatibility
Where this runs
tested against v4.12.0.20250516 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BeautifulSoup
✓ from bs4 import BeautifulSoup
✗ from bs4-stubs import BeautifulSoup
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}")
Debug
Known issues
breakingStarting 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.fixpip uninstall types-beautifulsoup4
affects: beautifulsoup4 >= 4.13.0
gotchaInstalling `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.fixEnsure `beautifulsoup4` is installed alongside `types-beautifulsoup4` (e.g., `pip install beautifulsoup4 types-beautifulsoup4`).
affects: All
gotchaType 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.fixPin 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.
affects: All
gotchaTypeshed, 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.fixConsider 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.
affects: All
gotchaMethods 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.fixUse 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.
affects: All
Upgrade
Version history
4.12.0.20250516latest on PyPI · released May 16, 2025
Audit
Dependencies
beautifulsoup4requiredProvides the actual runtime library for which these are type stubs.