requests-html：requests 作者出品的 HTML 解析库（内置 JS 渲染）｜安装与使用指南

仓库：https://github.com/kennethreitz/requests-html 许可证：MIT Python 版本要求：Python 3.6+ 定位：让 HTML 解析（爬虫）像 requests 一样简单

1. 项目简介与定位

requests-html 是 requests 作者 Kenneth Reitz 推出的、面向"人类"的 HTML 解析库。官方 README 标题就是 "Requests-HTML: HTML Parsing for Humans™"。它在 requests 之上包了一层解析能力：你用 HTMLSession() 发请求，拿到的响应对象直接就能 .html.find(...)、.html.xpath(...)、.html.links，甚至 .html.render() 用内置 Chromium 把 JavaScript 渲染出来再解析。

它把"发请求 + 解析 HTML + 跑 JS"三件事合成一个会话对象，主打一个简洁。注意它和 requests 是两个不同的库：requests 只发请求不解析，requests-html 是在 requests 生态里新写的解析层。

1.1 核心信息一览

项目	内容
仓库	kennethreitz/requests-html
定位	发请求 + HTML 解析 + 内置 JS 渲染
开源协议	MIT
安装方式	`pipenv install requests-html`（官方示例）/ `pip install requests-html`
Python 版本	官方 README 写明：Python 3.6 and above
关键依赖	requests、pyppeteer（首次 render 时下载 Chromium）

1.2 适用场景

想要 requests 那种一句话发请求的体验，同时直接在响应对象上选 CSS 选择器；
页面里有 JavaScript 渲染出来的内容，想顺手用 .render() 跑一遍；
需要异步并发抓多个站（AsyncHTMLSession）；
做小脚本、原型验证，不想分别拼 requests + BeautifulSoup + pyppeteer。

2. 开源协议

3. 官方仓库链接

仓库主页：https://github.com/kennethreitz/requests-html
PyPI：https://pypi.org/project/requests-html/
底层依赖 pyppeteer：https://github.com/pyppeteer/pyppeteer

4. 前置要求

来自官方 README：

Python 3.6 或更高版本；
操作系统：Linux / macOS / Windows 均可；
首次调用 r.html.render() 时，会通过 pyppeteer 自动下载 Chromium 到用户目录（~/.pyppeteer/），需要网络可访问下载源；
如果只用同步/异步请求与静态 HTML 解析、不调用 render()，则不需要 Chromium；
需要一个可用的 Python 包管理器（pip 或 pipenv）。

5. 安装部署

官方 README "Installation" 章节原文：

$ pipenv install requests-html
✨🍰✨

如果不用 pipenv，等价做法是：

$ pip install requests-html

首次使用 render() 时 pyppeteer 会自动拉取 Chromium，这一步只发生一次，下载到 ~/.pyppeteer/。

6. 最小示例代码

6.1 同步 GET（官方 README 原文）

from requests_html import HTMLSession
session = HTMLSession()
r = session.get('https://python.org/')

抓页面上所有链接：

r.html.links            # 相对/绝对混合
r.html.absolute_links   # 全部转成绝对 URL

用 CSS 选择器取元素：

about = r.html.find('#about', first=True)
print(about.text)
print(about.attrs)
print(about.html)

按官方 README 示例在 Chrome DevTools 里复制选择器直接用：

r = session.get('https://github.com/')
sel = 'body > div.application-main > div.jumbotron.jumbotron-codelines > div > div > div.col-md-7.text-center.text-md-left > p'
print(r.html.find(sel, first=True).text)

也支持 XPath：

r.html.xpath('/html/body/div[1]/a')

6.2 异步并发（官方 README 原文）

from requests_html import AsyncHTMLSession
asession = AsyncHTMLSession()

async def get_pythonorg():
    r = await asession.get('https://python.org/')
    return r

async def get_reddit():
    r = await asession.get('https://reddit.com/')
    return r

async def get_google():
    r = await asession.get('https://google.com/')
    return r

results = asession.run(get_pythonorg, get_reddit, get_google)
for result in results:
    print(result.html.url)

官方提示：results 列表的顺序是"响应返回顺序"，不是协程传入 run() 的顺序。

6.3 渲染 JavaScript

r = session.get('https://pythonclock.org')
r.html.render()                       # 首次会下载 Chromium
print(r.html.search('Python 2.7 will retire in...{}Enable Guido Mode')[0])

异步版本：

async def get_pyclock():
    r = await asession.get('https://pythonclock.org/')
    await r.html.arender()
    return r

results = asession.run(get_pyclock, get_pyclock, get_pyclock)

6.4 不发请求、直接解析字符串

from requests_html import HTML
doc = "<a href='https://httpbin.org'>"
html = HTML(html=doc)
html.links

7. 配置项

requests-html 没有配置文件，常用调用参数：

配置点	作用
`HTMLSession()` / `AsyncHTMLSession()`	创建会话，可传 requests 风格的 headers、cookies、auth
`session.get/post(...)`	单次请求，参数与 requests 一致
`r.html.find(selector, first=True)`	CSS 选择器；`first=True` 只返回第一个
`r.html.xpath(path)`	XPath 选择
`r.html.search(template)`	用 `{}` 占位符从文本里抽字段
`r.html.render()` / `r.html.arender()`	调用 pyppeteer 跑 Chromium 渲染 JS

官方 README 提到的行为：自动跟随重定向、连接池与 Cookie 持久化、自带 Mocked User-Agent。

8. 常见问题

和 requests 是什么关系？ 作者相同，但不是同一个包。requests 只发请求；requests-html 额外包了 HTML 解析与 JS 渲染，是独立安装的另一个库。
render() 卡住或下载 Chromium 失败？ 首次 render 会从 pyppeteer 默认源下 Chromium，国内网络可能需要配镜像或手动放好 Chromium 到 ~/.pyppeteer/。
不跑 JS 也要装 Chromium 吗？ 不用。只有调用 .render() / .arender() 才会触发下载。
异步结果顺序不对？ 官方 README 明确说明：results 顺序是响应返回顺序，不是传入 run() 的顺序。
能在生产高并发里用吗？ requests-html 是面向"人类友好"的小工具，底层 pyppeteer 跑 Chromium 较重；大规模生产建议直接上 playwright / pyppeteer 原生 API。
Python 版本要求？ 官方 README 写明 "Only Python 3.6 and above is supported."

9. 与同类工具对比

vs requests + BeautifulSoup：两者拼装是工业界主流，控制力强；requests-html 把它们合成一个对象，写起来最短，但灵活性稍弱。
vs httpx：httpx 是现代 HTTP 客户端，不内置 HTML 解析；requests-html 主打"发请求 + 解析 + 跑 JS"一站式。
vs playwright / pyppeteer：后两者是完整浏览器自动化，能点按钮、截图、跑复杂 SPA；requests-html 只做"打开页面 → 拿 HTML → 选元素"。
vs parsel：parsel 在 lxml 之上统一 CSS/XPath，不发请求；requests-html 自带会话。

10. 许可

requests-html 以 MIT 许可证发布：

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

具体条款以仓库 LICENSE 原文为准。

11. 责任使用声明

使用 requests-html 进行网页数据采集时，请遵守以下原则：

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