Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 0.17.0 instead.
Reason given by maintainers: Windows missing

curl_cffi

PyPI - Downloads PyPI - Python Version PyPI version Generic badge Generic badge

Documentation

Python binding for curl-impersonate fork via cffi. For commercial support, visit impersonate.pro.

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.9 is the minimum supported version since v0.10.

Sponsors

Maintenance of this project is made possible by all the contributors and sponsors. If you'd like to sponsor this project and have your avatar or company logo appear below click here. 💖


SerpAPI

Scrape Google and other search engines from SerpApi's fast, easy, and complete API. 0.66s average response time (≤ 0.5s for Ludicrous Speed Max accounts), 99.95% SLAs, pay for successful responses only.


Bypass Cloudflare with API

Yes Captcha!

Yescaptcha is a proxy service that bypasses Cloudflare and uses the API interface to obtain verified cookies (e.g. cf_clearance). Click here to register: https://yescaptcha.com/i/stfnIO


Easy Captcha Bypass for Scraping

CapSolver

CapSolver is an AI-powered tool that easily bypasses Captchas, allowing uninterrupted access to public data. It supports a variety of Captchas and works seamlessly with curl_cffi, Puppeteer, Playwright, and more. Fast, reliable, and cost-effective. Plus, curl_cffi users can use the code "CURL" to get an extra 6% balance! and register here.


Features

  • 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.
  • 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 & 3.0, which requests does not.
  • Supports websocket.
requests aiohttp httpx pycurl curl_cffi
http/2 ❌ ❌ ✅ ✅ ✅
http/3 ❌ ❌ ❌ ☑️1 ☑️2
sync ✅ ❌ ✅ ✅ ✅
async ❌ ✅ ✅ ❌ ✅
websocket ❌ ✅ ❌ ❌ ✅
fingerprints ❌ ❌ ❌ ❌ ✅
speed 🐇 🐇🐇 🐇 🐇🐇 🐇🐇

Notes:

  1. For pycurl, you need a http/3 enabled libcurl to make it work, while curl_cffi packages libcurl-impersonate inside Python wheels.
  2. Since v0.11.0. However, only Linux and macOS are supported, Windows is not supported due to failed building of ngtcp2.

Install

pip install curl_cffi --upgrade

This should work on Linux, macOS and Windows out of the box. If it does not work on you platform, you may need to compile and install curl-impersonate first and set some environment variables like LD_LIBRARY_PATH.

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 .

On macOS, you may need to install the following dependencies:

brew install zstd nghttp2

Usage

curl_cffi comes with a low-level curl API and a high-level requests-like API.

requests-like

v0.9:

from curl_cffi import requests

r = requests.get("https://tls.browserleaks.com/json", impersonate="chrome")

v0.10:

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")

# Randomly choose a browser version based on current market share in real world
# from: https://caniuse.com/usage-table
# NOTE: this is a pro feature.
r = curl_cffi.get("https://example.com", impersonate="realworld")

# 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)

Sessions

v0.9:

from curl_cffi import requests

s = requests.Session()

v0.10:

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'}}

Supported impersonate browsers

curl_cffi supports the same browser versions as supported by my fork of curl-impersonate:

Open source version of curl_cffi includes versions whose fingerprints differ from previous versions. If you see a version, e.g. chrome135, were skipped, you can simply impersonate it with your own headers and the previous version.

If you don't want to look up the headers etc, by yourself, consider buying commercial support from impersonate.pro, we have comprehensive browser fingerprints database for almost all the browser versions on various platforms.

If you are trying to impersonate a target other than a browser, use ja3=... and akamai=... to specify your own customized fingerprints. See the docs on impersonation for details.

Browser Open Source Pro version
Chrome chrome99, chrome100, chrome101, chrome104, chrome107, chrome110, chrome116[1], chrome119[1], chrome120[1], chrome123[3], chrome124[3], chrome131[4], chrome133a[5][6], chrome136[6] chrome132, chrome134, chrome135
Chrome Android chrome99_android, chrome131_android [4] chrome132_android, chrome133_android, chrome134_android, chrome135_android
Chrome iOS N/A coming soon
Safari [7] safari15_3 [2], safari15_5 [2], safari17_0 [1], safari18_0 [4], safari18_4 [6] coming soon
Safari iOS [7] safari17_2_ios[1], safari18_0_ios[4], safari18_4_ios [6] coming soon
Firefox firefox133[5], firefox135[7] coming soon
Firefox Android N/A firefox135_android
Tor tor145 [7] coming soon
Edge edge99, edge101 edge133, edge135
Opera N/A coming soon
Brave N/A coming soon

Notes:

  1. Added in version 0.6.0.
  2. Fixed in version 0.6.0, previous http2 fingerprints were not correct.
  3. Added in version 0.7.0.
  4. Added in version 0.8.0.
  5. Added in version 0.9.0.
  6. The version postfix -a(e.g. chrome133a) means that this is an alternative version, i.e. the fingerprint has not been officially updated by browser, but has been observed because of A/B testing.
  7. Added in version 0.10.0.
  8. Added in version 0.11.0.
  9. Since 0.11.0, the format safari184_ios is preferred over safari18_4_ios, both are supported, but the latter is quite confusing and hard to parse.

Asyncio

from curl_cffi import AsyncSession

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

More concurrency:

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 for more details.

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 WebSockets

import asyncio
from curl_cffi import AsyncSession

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

Ecosystem

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.

Metadata

Release files for curl-cffi 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for curl-cffi 0.11.0
File Size Uploaded Provenance Actions
curl_cffi-0.11.0.tar.gz 148.0 kB Without provenance Details for curl_cffi-0.11.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for curl-cffi 0.11.0
File Actions
curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_x86_64.whl CPython 3.9 abi3 Linux musl 1.1+ x86-64 Details for curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_x86_64.whl
curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_aarch64.whl CPython 3.9 abi3 Linux musl 1.1+ ARM64 Details for curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_aarch64.whl
curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-32 Details for curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
curl_cffi-0.11.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for curl_cffi-0.11.0-cp39-abi3-macosx_11_0_arm64.whl
curl_cffi-0.11.0-cp39-abi3-macosx_10_9_x86_64.whl CPython 3.9 abi3 macOS 10.9+ x86-64 Details for curl_cffi-0.11.0-cp39-abi3-macosx_10_9_x86_64.whl

Total release size: 50.8 MB

Release files / curl_cffi-0.11.0.tar.gz

Download URL curl_cffi-0.11.0.tar.gz
Size 148.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f5fc6b80d35afe2ae8e2e6402ca05ca9f8a997eff2af36b1a0d8b0604200057e
BLAKE2b-256 checksum
How to use checksums
a0856829d63306c0574074795a0700bd1f95ceade5812c452bce5cf563ee84d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_x86_64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_x86_64.whl
Size 8.9 MB
Tags CPython 3.9 Linux musl 1.1+ x86-64 abi3
SHA-256 checksum
How to use checksums
d8b30ed44d39bff3060c2d157663dc90779b1a7ff900603f7338e7774601a344
BLAKE2b-256 checksum
How to use checksums
3814478188771a27f46946f527dc9af6d247cfd938e576e29dec691dec7d7178
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_aarch64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-musllinux_1_1_aarch64.whl
Size 8.9 MB
Tags CPython 3.9 Linux musl 1.1+ ARM64 abi3
SHA-256 checksum
How to use checksums
90e9ee1882eb980a25eec11c383e5a799697bec960ff185625fa230734a8727e
BLAKE2b-256 checksum
How to use checksums
746b35deb083c936256c97f8f0ab36e315cb024863c384e211c311f5dc03cbf1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 8.5 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
896f015d62eaba5052cdf7d7ea67e3dfcfa6658968f8c7b872eaf4b8b094dd36
BLAKE2b-256 checksum
How to use checksums
70b51591d65b776035652a644862291a807cf5767a8fc1b922a16649d11f954a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl

Download URL curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
Size 7.7 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-32 abi3
SHA-256 checksum
How to use checksums
cc28dae508d21753af9cfd7f5d164533205d6e614da6a3832d813f5624083e7c
BLAKE2b-256 checksum
How to use checksums
d8a4821d64137a91557828b1b41dac710bf75a635beeb6ce905113e3b27c61cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 8.1 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1b10e07a1a29e6ac6054a2602aae40377b57dc7ff04c48e0ba8bf19f2ad80837
BLAKE2b-256 checksum
How to use checksums
941e453ce6eefde2b4dae1b3cd2675fc6fdecc54d5dec9494f0048b3877d7879
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-macosx_11_0_arm64.whl
Size 3.0 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
485b1476b6eb8916fb6cf6d307c71dd75c61fd232482c37f96ecb0e892552bdb
BLAKE2b-256 checksum
How to use checksums
cd75b23ebd83de548e7f1bfa6ce6bf5c8e08952ec75c50e64c811bc7dbde2b94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Release files / curl_cffi-0.11.0-cp39-abi3-macosx_10_9_x86_64.whl

Download URL curl_cffi-0.11.0-cp39-abi3-macosx_10_9_x86_64.whl
Size 5.7 MB
Tags CPython 3.9 abi3 macOS 10.9+ x86-64
SHA-256 checksum
How to use checksums
5afc71851e620b9f46a3e5cac821b05149b274484df3391e2ca5902c4eaa92a6
BLAKE2b-256 checksum
How to use checksums
4754132334dddb89d038d6d2a5d99aad3b47ca8d466084fe99e0c693ef348ae3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.8

Security for curl-cffi 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.11.0 This release

8 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page