Beautiful Soup 4：最经典的 Python HTML 解析库｜安装与使用指南

官方网站：https://www.crummy.com/software/BeautifulSoup/bs4/ 官方文档：https://www.crummy.com/software/BeautifulSoup/bs4/doc/ 包名：beautifulsoup4（PyPI） 许可证：MIT Python 版本要求：≥ 3.7

1. 项目简介与定位

Beautiful Soup 4（简称 BS4）是 Python 生态里最经典的 HTML/XML 解析库。它把一段不规范的 HTML 解析成一棵可遍历的元素树，让你用标签名、属性、CSS 选择器就能捞出想要的数据，而不用写一堆脆弱的正则。

官方文档原话："You didn't write that awful page. You're just trying to get some data out of it. Beautiful Soup is here to help."——它的设计目标就是帮你对付互联网上那些写得乱七八糟的 HTML。

1.1 核心信息一览

1.2 适用场景

• 已经用 requests / httpx 把页面抓回来，需要从 HTML 里抠标题、列表、链接；
• 面对的是写法不规范、标签没闭合的真实网页，需要容错解析；
• 想写得像 soup.select('div.article h2') 这样直观，不想直接碰 XPath；
• 配合 lxml 作为底层解析器，兼顾易用性与速度。

2. 开源协议

Beautiful Soup 4 以 MIT 许可证发布。允许商用、修改、再分发，义务仅为保留版权声明与许可文本。

3. 官方仓库与下载链接

• 官方首页：https://www.crummy.com/software/BeautifulSoup/bs4/
• 官方文档：https://www.crummy.com/software/BeautifulSoup/bs4/doc/
• 源码下载：https://www.crummy.com/software/BeautifulSoup/bs4/download/
• PyPI 项目页：https://pypi.org/project/beautifulsoup4/

说明：早期 GitHub 仓库 waylan/beautifulsoup 当前已无法通过公开 URL 访问（返回 404），官方主要以 PyPI 与 crummy.com 站点分发源码与文档。本文命令与用法以官方文档与 PyPI 元数据为准。

4. 前置要求

• Python 3.7 或更高版本（PyPI 元数据 Requires-Python >= 3.7.0）；
• 操作系统：Linux / macOS / Windows 均可；
• 可选底层解析器：
  • Python 标准库自带的 html.parser（零依赖，默认）；
  • lxml（速度快，需另行 pip install lxml）；
  • html5lib（按浏览器规则解析 HTML5，需另行安装）；
• Debian / Ubuntu 用户也可直接用系统包：sudo apt-get install python3-bs4。

5. 安装部署

官方文档 "Installing Beautiful Soup" 章节给出的命令：

$ pip install beautifulsoup4

注意：PyPI 上还有一个叫 BeautifulSoup 的包，那是已经停止维护的 3.x 老版本，不要装错。写新代码一律装 beautifulsoup4，导入时 from bs4 import BeautifulSoup。

Debian / Ubuntu 系统包：

$ sudo apt-get install python3-bs4

如果想要更快的解析速度，顺带装 lxml：

$ pip install beautifulsoup4 lxml

6. 最小示例代码

官方文档入门示例：

from bs4 import BeautifulSoup

html_doc = """
<html><head><title>The Dormouse's story</title></head>
<body>
<p class="title"><b>The Dormouse's story</b></p>

<p class="story">Once upon a time there were three little sisters; and their names were
<a href="http://example.com/elsie" class="sister" id="link1">Elsie</a>,
<a href="http://example.com/lacie" class="sister" id="link2">Lacie</a> and
<a href="http://example.com/tillie" class="sister" id="link3">Tillie</a>;
and they lived at the bottom of a well.</p>
"""

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

print(soup.title.string)            # The Dormouse's story
print(soup.find_all('a'))           # 三个 <a> 标签
print([a.get('href') for a in soup.find_all('a')])

配合 httpx 抓取真实页面：

import httpx
from bs4 import BeautifulSoup

r = httpx.get('https://example.org/')
soup = BeautifulSoup(r.text, 'lxml')
for h1 in soup.select('h1'):
    print(h1.get_text(strip=True))

7. 配置项

BS4 没有配置文件，关键"配置"是构造 BeautifulSoup 时选的解析器：

官方文档 "Installing a parser" 章节有完整对照表。常用 API 包括 find / find_all / select / select_one / get_text()。

8. 常见问题

• pip install BeautifulSoup 装到了老版本？ 老包叫 BeautifulSoup（3.x，已停维护），新代码必须装 beautifulsoup4。
• 导入报 ModuleNotFoundError: No module named 'bs4'？ 包名和导入名不一样：装的是 beautifulsoup4，导入是 from bs4 import BeautifulSoup。
• 解析速度慢？ 把第二个参数从 'html.parser' 换成 'lxml'（需先装 lxml），通常快一个量级。
• 页面不规范、标签没闭合？ 试试 html5lib，它按浏览器容错规则解析；或用 lxml 配合 recover=True。
• 能直接发请求吗？ 不能。BS4 只解析字符串，抓页面请用 requests / httpx。
• 和 lxml 是什么关系？ BS4 是上层 API，lxml 是可选的底层解析器，两者不是互斥而是搭配使用。

9. 与同类工具对比

• vs lxml：lxml 速度快、API 偏 XML 风格；BS4 更贴近"给我一段 HTML 我帮你找东西"的直觉，且容错更好，但默认解析器较慢。实战常用 BeautifulSoup(markup, "lxml")。
• vs pyquery：pyquery 让你像写 jQuery 一样操作 DOM，底层也是 lxml；BS4 是更老牌、文档更全的选择。
• vs parsel / selectolax：parsel 在 lxml 之上统一了 CSS 与 XPath；selectolax 是另一套高速引擎。BS4 胜在入门门槛低、Stack Overflow 答案多。
• vs 正则：不要用正则解析 HTML，BS4 就是为了替代正则而生。

10. 许可

Beautiful Soup 4 以 MIT 许可证发布：

• 允许个人与商业使用、修改、再分发；
• 允许闭源衍生作品；
• 再分发时需保留版权声明与 MIT 许可文本。

具体条款以官方源码包内 LICENSE 与文档声明为准。

11. 责任使用声明

使用 Beautiful Soup 4 进行网页数据采集时，请遵守以下原则：

1. 遵守目标网站的 robots.txt 与服务条款（ToS），不采集明确禁止抓取的路径；
2. 控制请求并发与间隔，避免对目标服务器造成压力；
3. 不绕过登录态、付费墙或反爬机制，不伪造身份获取付费内容；
4. 不批量抓取个人隐私数据，不收集、存储、传播可识别个人身份的信息；
5. 仅将解析得到的公开数据用于学习、研究与合规的业务用途；
6. 尊重原作者版权，转载或二次发布内容时注明来源并遵守相应授权。