curl_cffi - Python binding for curl-impersonate

Curl_cffi, the most popular Python binding for curl-impersonate, now supports http/3 fingerprints and UDP socks5 proxy as of v0.15.0, and requires Python 3.10 since v0.14. The library allows browsers' TLS/JA3 and HTTP/2 fingerprint impersonation to bypass website blocking, and is faster than requests/httpx.

Python binding for curl-impersonate fork https://github.com/lexiforest/curl-impersonate via cffi https://cffi.readthedocs.io/en/latest/ . For commercial support, visit impersonate.pro https://impersonate.pro . curl cffi is the most popular Python binding for curl . Unlike other pure python http clients like httpx or requests , curl cffi can impersonate browsers' TLS/JA3 and HTTP/2 fingerprints. If you are blocked by some website for no obvious reason, you can give curl cffi a try. Python 3.10 is the minimum supported version since v0.14. - 💨 http/3 fingerprints and UDP socks5 proxy support was added in v0.15.0 - 🦞 Added curl-cffi CLI and skills for debugging and for claws/agents. If you’re looking for a meeting recording API, consider checking out Recall.ai https://www.recall.ai/?utm source=github&utm medium=sponsorship&utm campaign=lexiforest-curl cffi , an API that records Zoom, Google Meet, Microsoft Teams, in-person meetings, and more. Maintenance of this project is made possible by all the contributors https://github.com/lexiforest/curl cffi/graphs/contributors and sponsors https://github.com/sponsors/lexiforest . If you'd like to sponsor this project and have your avatar or company logo appear below click here https://github.com/sponsors/lexiforest . 💖 Yescaptcha is a proxy service that bypasses Cloudflare and uses the API interface to obtain verified cookies e.g. cf clearance . Click here https://yescaptcha.com/i/stfnIO to register: https://yescaptcha.com/i/stfnIO https://yescaptcha.com/i/stfnIO TLS fingerprinting alone isn't enough for modern bot protection. Hyper Solutions https://hypersolutions.co?utm source=github&utm medium=readme&utm campaign=curl cffi provides the missing piece - API endpoints that generate valid antibot tokens for: Akamai • DataDome • Kasada • Incapsula No browser automation. Just simple API calls that return the exact cookies and headers these systems require. 🚀 Get Your API Key https://hypersolutions.co?utm source=github&utm medium=readme&utm campaign=curl cffi | 📖 Docs https://docs.justhyped.dev | 💬 Discord https://discord.gg/akamai curl-cffi is part of the impersonate suite. curl-impersonate https://github.com/lexiforest/curl-impersonate . A curl distribution that impersonates browsers. curl cffi https://github.com/lexiforest/curl cffi . Python binding to curl-impersonate. impers https://github.com/lexiforest/impers . Node.js binding to curl-impersonate. impersonate.pro https://impersonate.pro . Commercial support, more fingerprints and integrated solutions. - Supports JA3/TLS and http2 fingerprints impersonation, including recent browsers and custom fingerprints. - Much faster than requests/httpx, on par with aiohttp/pycurl, see benchmarks https://github.com/lexiforest/curl cffi/tree/main/benchmark . - Mimics the requests API, no need to learn another one. - Pre-compiled, so you don't have to compile on your machine. - Supports asyncio with proxy rotation on each request. - Supports http 2.0, which requests does not. - Supports http 3.0, with fingerprints and udp proxy. - Supports websocket. - MIT licensed. | requests | aiohttp | httpx | pycurl | curl cffi | | |---|---|---|---|---|---| | http/2 | ❌ | ❌ | ✅ | ✅ | ✅ | | http/3 | ❌ | ❌ | ❌ | ☑️1 | ✅2 | | sync | ✅ | ❌ | ✅ | ✅ | ✅ | | async | ❌ | ✅ | ✅ | ❌ | ✅ | | websocket | ❌ | ✅ | ❌ | ❌ | ✅ | | native retry | ❌ | ❌ | ❌ | ❌ | ✅ | | fingerprints | ❌ | ❌ | ❌ | ❌ | ✅ | | speed | 🐇 | 🐇🐇 | 🐇 | 🐇🐇 | 🐇🐇 | Notes: - For pycurl, http/3 is usually disabled at compile time by default. - http/3 support since v0.11.4, http/3 proxy and fingerprints since v0.15.0. Since v0.15, curl cffi comes with a CLI called curl-cffi , you can use it for debugging a certain url with the --impersonate option. It can also serve as a web fetch replacement for "claws" and "agents". | curl | httpie | curl-cffi | | |---|---|---|---| | http/2 | ✅ | ❌ | ✅ | | http/3 | ☑️1 | ❌ | ✅ | | human-friendly | ☑️2 | ✅ | ✅ | | colorful | ❌ | ✅ | ✅3 | | fingerprints | ❌ | ❌ | ✅ | Notes: - You need an http/3 enabled curl build, it's not enabled by default, at leat on my machine. - As a long time command line user, I personally feel very comfortable using curl -X POST httpbin.org , but some users may prefer http GET httpbin.org syntax. If you prefer the curl syntax, you can keep using curl-impersonate . - Install curl cffi cli for colorful CLI output. Without rich , the CLI uses plain text output. pip install curl cffi --upgrade This should work on Linux, macOS and Windows out of the box. On macOS, you can also install via Homebrew: brew install lexiforest/tap/curl-cffi Android support, including Termux, is currently in beta, you can install the beta release for testing. For BSD systems, we need to get libcurl-impersonate compile first, and then add support in curl cffi. If you are using these OSes, please lend an hand. To install beta releases: pip install curl cffi --upgrade --pre To install unstable version from GitHub: git clone https://github.com/lexiforest/curl cffi/ cd curl cffi make preprocess pip install . curl cffi comes with a low-level curl API and a high-level requests -like API. curl cffi also bundles with a CLI called curl-cffi . 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 For a complete CLI guide, see docs https://curl-cffi.readthedocs.io . python 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 supports the same browser versions preset as supported by our fork https://github.com/lexiforest/curl-impersonate of curl-impersonate https://github.com/lwthiker/curl-impersonate : The open source version of curl cffi includes versions when we are adding new capabilities for impersonating. If you see a version, e.g. chrome135 , was skipped, it's simply because there's nothing new or we were busy at that time. You can simply impersonate it with your own headers and the previous browser target. For a full list of preset fingerprints, see the curl-impersonate docs https://curl-impersonate.readthedocs.io/en/latest/fingerprints.html . We will no longer put duplicated and outdated info here. If you don't want to look up the headers/etc by yourself, consider buying commercial support from impersonate.pro https://impersonate.pro . We have comprehensive browser tls, http and JavaScript fingerprints database for almost all the browser versions on various platforms. Since v0.15.1, you can use curl-cffi update to retrieve the latest fingerprints, without updating to a new version. We offer the Safari, Chrome, Firefox updates for free and others as part of the commercial plan https://impersonate.pro . The current number of fingerprints: To see the current list of fingerprints on your device, use the command line: curl-cffi list To update fingerprints from impersonate.pro, use the command line: curl-cffi update If you are trying to impersonate a target other than a browser, use ja3=... , akamai=... , extra fp=... , and perk=... to specify your own customized fingerprints. See the docs on impersonation https://curl-cffi.readthedocs.io/en/latest/impersonate/ index.html for details. python from curl cffi import AsyncSession async with AsyncSession as s: r = await s.get "https://example.com" More concurrency: python 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 For low-level APIs, Scrapy integration and other advanced topics, see the docs https://curl-cffi.readthedocs.io for more details. python 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" python 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 https://curl-cffi.readthedocs.io/en/latest/websockets.html for full details and advanced options. - Integrating with Scrapy: divtiply/scrapy-curl-cffi https://github.com/divtiply/scrapy-curl-cffi , jxlil/scrapy-impersonate https://github.com/jxlil/scrapy-impersonate and tieyongjie/scrapy-fingerprint https://github.com/tieyongjie/scrapy-fingerprint . - Integrating with requests https://github.com/el1s7/curl-adapter , httpx https://github.com/vgavro/httpx-curl-cffi as adapter. - Integrating with captcha resolvers: YesCaptcha https://yescaptcha.com/i/stfnIO . - Originally forked from multippt/python curl cffi https://github.com/multippt/python curl cffi , which is under the MIT license. - Headers/Cookies files are copied from httpx https://github.com/encode/httpx/blob/master/httpx/ models.py , 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 https://github.com/websocket-client/websocket-client . - The asynchronous WebSocket API is inspired by aiohttp https://github.com/aio-libs/aiohttp . 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 - 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 https://simonwillison.net/2025/Dec/18/code-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 https://discourse.llvm.org/t/rfc-llvm-ai-tool-policy-human-in-the-loop/89159 You can even feed the policy above to your "copilot" to let it adjust the style for you. :P