curl_cffi

文档

基于 cffi 实现 curl-impersonate fork 的 Python 绑定。如需商业支持，请访问 impersonate.pro。

curl_cffi 是 curl 最受欢迎的 Python 绑定。与 httpx 或 requests 等其他纯 Python HTTP 客户端不同，curl_cffi 可以模拟浏览器的 TLS/JA3 与 HTTP/2 指纹。如果你访问某些网站时没有明显原因却被拦截，不妨试试 curl_cffi。

如需 JavaScript 绑定，请参见 impers；如需解决 JavaScript 质询，请参见 brimp。

自 v0.14 起，Python 3.10 是最低支持版本。

近期亮点

• 🧭 我们的新玩具 brimp，一款轻量级浏览器，类似启用了 JavaScript 的 curl_cffi。今天就试试看！
• 🆕 新增对 Chrome 150/152 中新算法与扩展的支持。

Recall.ai - 会议录音 API

如果你在寻找会议录音 API，不妨查看 Recall.ai，这是一个可录制 Zoom、Google Meet、Microsoft Teams、线下会议等的 API。

赞助商

本项目的维护得以实现，离不开所有贡献者和赞助者。如果你想赞助本项目，并让你的头像或公司标志展示在下方，点击这里。💖

---

通过 API 绕过 Cloudflare

Yescaptcha 是一项代理服务，可绕过 Cloudflare，并通过 API 接口 获取已验证的 Cookie（例如 cf_clearance）。点击此处 注册：https://yescaptcha.com/i/stfnIO

---

仅靠 TLS 指纹不足以应对现代机器人防护。Hyper Solutions 补齐了缺失的一环——提供可生成有效反机器人令牌的 API 端点，适用于：

Akamai • DataDome • Kasada • Incapsula

无需浏览器自动化。只需简单的 API 调用，即可返回这些系统所需的确切 Cookie 和请求头。

🚀 获取您的 API Key | 📖 文档 | 💬 Discord

---

cloro：面向 Google、ChatGPT、Perplexity、Gemini、Copilot 和 Grok 的 SERP 与 AI 搜索 API

Impersonate 套件

curl-cffi 属于 Impersonate 套件。

• curl-impersonate. 一款能够仿真浏览器的 curl 发行版。
• curl_cffi. curl-impersonate 的 Python 绑定。
• brimp. Browser-impersonate，一款轻量级浏览器
• impers. curl-impersonate 的 Node.js 绑定。
• impersonate.pro. 提供商业支持、更多指纹以及云服务。

功能

• 支持 JA3/TLS 与 http2 指纹仿真，包括较新的浏览器和自定义指纹。
• 速度远快于 requests/httpx，与 aiohttp/pycurl 相当，详见 基准测试。
• 模拟 requests API，无需额外学习新接口。
• 提供预编译版本，无需在本地机器上自行编译。
• 支持 asyncio，并可在每个请求时轮换代理。
• 支持 http 2.0，这是 requests 所不具备的。
• 支持 http 3.0，并支持指纹和 udp 代理。
• 支持 websocket。
• 采用 MIT 许可证。

	requests	aiohttp	httpx	pycurl	curl_cffi
http/2	❌	❌	✅	✅	✅
http/3	❌	❌	❌	☑️1	✅2
同步	✅	❌	✅	✅	✅
异步	❌	✅	✅	❌	✅
websocket	❌	✅	❌	❌	✅
原生重试	❌	❌	❌	❌	✅
指纹	❌	❌	❌	❌	✅
速度	🐇	🐇🐇	🐇	🐇🐇	🐇🐇

说明：

1. 对于 pycurl，http/3 通常在编译时默认禁用。
2. 自 v0.11.4 起支持 http/3，自 v0.15.0 起支持 http/3 代理和指纹。

安装

pip install curl_cffi --upgrade

在 Linux、macOS 和 Windows 上通常开箱即用。

在 macOS 上，也可以通过 Homebrew 安装：

brew install lexiforest/tap/curl-cffi

安装 beta 版本：

pip install curl_cffi --upgrade --pre

从 GitHub 安装不稳定版本：

git clone https://github.com/lexiforest/curl_cffi/ cd curl_cffi make preprocess pip install .

使用

curl_cffi 提供低层 curl API 和类似 requests 的高层 API。 curl_cffi 还附带一个名为 curl-cffi 的命令行工具。

CLI

自 v0.15 起，curl_cffi 内置了一个名为 curl-cffi 的命令行工具，你可以使用 --impersonate 选项来调试某个 URL。它也可以作为“智能体”的 web_fetch 替代方案。

curl-cffi get tls.browserleaks.com/json

# curl-cffi can be hard to type, use an alias if you want
alias imp=curl-cffi
imp get tls.browserleaks.com/json --impersonate chrome

如需完整的 CLI 指南，请参阅 文档。

requests 风格

import curl_cffi

# Notice the impersonate parameter
r = curl_cffi.get("https://tls.browserleaks.com/json", impersonate="chrome")

print(r.json())
# output: {..., "ja3n_hash": "aa56c057ad164ec4fdcb7a5a283be9fc", ...}
# the js3n fingerprint should be the same as target browser

# To keep using the latest browser version as `curl_cffi` updates,
# simply set impersonate="chrome" without specifying a version.
# Other similar values are: "safari" and "safari_ios"
r = curl_cffi.get("https://tls.browserleaks.com/json", impersonate="chrome")

# Use http/3 with impersonation
r = curl_cffi.get(
    "https://fp.impersonate.pro/api/http3",
    http_version="v3",
    impersonate="chrome"
)

# To pin a specific version, use version numbers together.
r = curl_cffi.get("https://tls.browserleaks.com/json", impersonate="chrome124")

# To impersonate other than browsers, bring your own ja3/akamai strings
# See examples directory for details.
r = curl_cffi.get("https://tls.browserleaks.com/json", ja3=..., akamai=...)

# http/socks proxies are supported
proxies = {"https": "http://localhost:3128"}
r = curl_cffi.get("https://tls.browserleaks.com/json", impersonate="chrome", proxies=proxies)

proxies = {"https": "socks://localhost:3128"}
r = curl_cffi.get("https://tls.browserleaks.com/json", impersonate="chrome", proxies=proxies)

会话

s = curl_cffi.Session()

# httpbin is a http test website, this endpoint makes the server set cookies
s.get("https://httpbin.org/cookies/set/foo/bar")
print(s.cookies)
# <Cookies[<Cookie foo=bar for httpbin.org />]>

# retrieve cookies again to verify
r = s.get("https://httpbin.org/cookies")
print(r.json())
# {'cookies': {'foo': 'bar'}}

支持的浏览器模拟版本

curl_cffi 支持与我们在 curl-impersonate 的 fork 中预设相同的浏览器版本：

curl_cffi 开源版本会在我们新增浏览器模拟能力时收录相应版本。 如果你看到某个版本（例如 chrome135）被跳过，只是因为没有新增内容，或者我们当时比较忙碌。 你可以直接使用自定义请求头并指定上一个浏览器目标来模拟它。

如需查看预设指纹的完整列表，请参考 curl-impersonate 文档。 此页不再重复冗余或过时的信息。

如果你不想自行查找请求头等配置，可以考虑从 impersonate.pro 购买商业支持。 我们拥有全面覆盖各平台几乎所有浏览器版本的浏览器 tls、http 和 JavaScript 指纹数据库。

自 v0.15.1 起，你可以使用 curl-cffi update 获取最新指纹，而无需升级到新版本。 我们免费提供 Safari、Chrome 和 Firefox 的更新，其他更新包含在 商业方案 中。

当前指纹数量：

要查看当前设备上的指纹列表，请使用命令行：

curl-cffi list

如需从 impersonate.pro 更新指纹，请使用命令行：

curl-cffi update

如果你希望伪装的目标不是浏览器，请使用 ja3=...、akamai=...、extra_fp=... 和 perk=... 来指定自定义指纹。更多详情，请参阅 impersonation 文档。

Asyncio

from curl_cffi import AsyncSession

async with AsyncSession() as s:
    r = await s.get("https://example.com")

更高并发：

import asyncio
from curl_cffi import AsyncSession

urls = [
    "https://google.com/",
    "https://facebook.com/",
    "https://twitter.com/",
]

async with AsyncSession() as s:
    tasks = []
    for url in urls:
        task = s.get(url)
        tasks.append(task)
    results = await asyncio.gather(*tasks)

如需了解底层 API、Scrapy 集成以及其他进阶主题，请参见 文档 了解更多详情。

WebSockets

from curl_cffi import WebSocket

def on_message(ws: WebSocket, message: str | bytes):
    print(message)

ws = WebSocket(on_message=on_message)
ws.run_forever("wss://api.gemini.com/v1/marketdata/BTCUSD")

Asyncio WebSocket

import asyncio
from curl_cffi import AsyncSession

async with AsyncSession() as session:
    async with session.ws_connect("wss://echo.websocket.org") as ws:
        await asyncio.gather(*[ws.send_str("Hello, World!") for _ in range(10)])
        async for message in ws:
            print(message)

See the WebSocket docs for full details and advanced options.

Ecosystem

• Integrating with Scrapy: divtiply/scrapy-curl-cffi, jxlil/scrapy-impersonate and tieyongjie/scrapy-fingerprint.
• Integrating with requests, httpx as adapter.
• Integrating with captcha resolvers: YesCaptcha.

Acknowledgement

• Originally forked from multippt/python_curl_cffi, which is under the MIT license.
• Headers/Cookies files are copied from httpx, which is under the BSD license.
• Asyncio support is inspired by Tornado's curl http client.
• The synchronous WebSocket API is inspired by websocket_client.
• The asynchronous WebSocket API is inspired by aiohttp.

Contributing

When submitting an PR, please use a different branch other than main and check the "Allow edits by maintainers" box, so I can update your PR with lint or style fixes. Thanks!

AI Policy

• Using AI is neither encouraged nor discouraged, use it by your own choice.
• The bottom line here is that every line of code should be reviewed by human, and should be proven to work.
• It's not guaranteed that AI will come up with the cleanest solution, you are responsible to guide it to the right way you know.
• Fix any lint errors, make sure your code follows the established convention in this project.
• LLM tends to generate extensive or none comments, revise the comments and make sure they are concise and helpful.
• It's absolutely not acceptable to generate the entire PR summary by LLM. To communicate with other human, use words from a human.
• The only acceptable exception is to fix grammar issues if you are not a native English speaker.
• The essence here is to keep Human in the loop

You can even feed the policy above to your "copilot" to let it adjust the style for you. 😛