curl-cffi

library0.16.2pypypi✓ verified 30d ago

curl-cffi is a Python binding for the curl-impersonate fork via CFFI. It enables Python applications to impersonate browsers' TLS/JA3 and HTTP/2 fingerprints, effectively bypassing many anti-bot systems. The library provides a high-level API that mimics the popular `requests` library, making it intuitive to use. It supports asynchronous operations, HTTP/2, HTTP/3, and WebSockets. The current stable version is 0.14.0, with active development and frequent updates.

http-networking web-framework

pip install curl-cffi

github ↗package ↗

INSTALL

IMPORT

SIG · CURL-CFFI

curl-cffi

http-networkingpythonv0.16.2

Install

2.3s avg

Import

385ms

Disk

53MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.408s · 56.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.362s · 58MB

53MB installed

● package 53MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

requests

✓ from curl_cffi import requests

✗ import requests; requests.get(..., impersonate='chrome')

The `requests` module from `curl_cffi` provides the impersonation capabilities, not the standard `requests` library.

Session

✓ from curl_cffi.requests import Session

AsyncSession

✓ from curl_cffi import AsyncSession

WebSocket

✓ from curl_cffi import WebSocket

This quickstart demonstrates how to make a basic GET request impersonating a specific browser (Chrome 110) and how to use a `Session` object for persistent connections with another impersonation profile (Safari 15.5) and cookie management. It includes basic error handling.

from curl_cffi import requests def main(): try: # Make a GET request impersonating Chrome response = requests.get('https://www.example.com', impersonate='chrome110') response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx) print(f"Status Code: {response.status_code}") print("Response Header:\n", response.headers) print("First 500 chars of Response Body:\n", response.text[:500]) # Using a session for persistent connections and cookies with requests.Session() as s: s.impersonate = 'safari15_5' res_session = s.get('https://httpbin.org/cookies/set/sessioncookie/123') print(f"\nSession Status Code: {res_session.status_code}") print(f"Session Cookies: {s.cookies.get('sessioncookie')}") except requests.exceptions.RequestError as e: print(f"An error occurred: {e}") if __name__ == '__main__': main()

Debug

Known issues

breakingAs of version 0.14.0, curl-cffi officially supports Python 3.10 and above. Older Python versions (e.g., 3.9) are no longer officially supported.

fix

Upgrade your Python environment to 3.10 or newer.

affects: >=0.14.0

breakingIn version 0.3.0, the `Response.cookies` attribute's type changed from `http.cookies.SimpleCookie` to `curl_cffi.requests.Cookies`. This might affect code expecting the standard library's cookie object for manipulation.

fix

Adjust cookie handling to use `curl_cffi.requests.Cookies` methods, which often mimic `requests.cookies.RequestsCookieJar`.

affects: >=0.3.0

gotchaWhen configuring HTTPS proxies, specifying the proxy URL with an `https://` scheme might lead to `OPENSSL_internal:WRONG_VERSION_NUMBER` errors. The `http://` scheme is often required for the proxy's URL.

fix

Change proxy configuration from `{"https": "https://localhost:3128"}` to `{"https": "http://localhost:3128"}`.

affects: All

gotchaThe error `ErrCode: 92, Reason: 'HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1)'` often occurs with HTTP/2 requests, sometimes due to proxies or server-side issues. Removing `Content-Length` headers or forcing HTTP/1.1 can be workarounds.

fix

Try removing the `Content-Length` header from your request or force HTTP/1.1 by setting `http_version=CurlHttpVersion.v1_1` in your request or session (e.g., `requests.get(url, http_version=CurlHttpVersion.v1_1)`).

affects: All

gotchaWhen handling streamed responses (e.g., `stream=True`), content is buffered in memory by default. If not consumed immediately, this can lead to Out Of Memory (OOM) errors for large responses. Using `iter_content()` or `content_callback` is recommended.

fix

Iterate over `response.iter_content()` immediately or use the native `content_callback` function for processing streamed content to prevent excessive memory usage.

affects: All

breakingThe exception hierarchy in `curl_cffi.requests.exceptions` differs from `requests`. Broad base exceptions like `requests.exceptions.RequestException` (or similar broad types like `RequestError` if used) might not exist or have different names in `curl-cffi`, leading to `AttributeError` when attempting to catch them.

fix

Adjust exception handling to catch specific `curl_cffi.requests.exceptions` types, such as `RequestsError` for general `curl-cffi` errors, or more specific ones like `SSLError` or `ConnectionError`.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named '_cffi_backend'

When packaging a `curl-cffi` application with PyInstaller, the `_cffi_backend` module and associated data files are often not automatically included in the final executable.

fix

Instruct PyInstaller to explicitly include the necessary modules and data files. Example: `pyinstaller -F your_script.py --hidden-import=_cffi_backend --collect-all curl_cffi`

ImportError: DLL load failed: The specified module could not be found.

This Windows-specific error typically occurs because the required Microsoft Visual C++ Redistributable libraries, essential for CFFI-based packages like `curl-cffi`, are missing or incompatible on the system. It can also indicate issues with the underlying `curl-impersonate` dependency.

fix

Install the latest Microsoft Visual C++ Redistributable for Visual Studio (usually 2015-2022) from the Microsoft website. Ensure `curl-cffi` is installed correctly, allowing it to use pre-compiled binaries or correctly link to `curl-impersonate`.

curl_cffi.CurlError: Failed to perform, ErrCode: 92, Reason: 'HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1)'

This HTTP/2 protocol error often arises from issues such as incorrect `Content-Length` headers, problems with the proxies being used, or a server's faulty HTTP/2 implementation.

fix

Try removing the `Content-Length` header from your request. Evaluate and switch to more reliable proxies if applicable. As a workaround, you can force the request to use HTTP/1.1 by adding `http_version=CurlHttpVersion.v1_1` to your `requests.get` or `Session.get` call.

ERROR: Failed building wheel for curl_cffi

This build error during `pip install` usually happens when pre-compiled binary wheels are not available for your specific operating system and Python version, and the system lacks the necessary development tools (like `curl-dev` or `libcurl4-openssl-dev` headers) to compile `curl-cffi` and its `curl-impersonate` dependency from source. An unsupported Python version can also contribute to this (e.g., Python < 3.10 for recent `curl-cffi` versions).

fix

Ensure your Python version meets the library's requirements (e.g., Python 3.10+ for `curl-cffi` v0.14.0). Install system-level development packages for curl (e.g., `sudo apt-get install libcurl4-openssl-dev` on Debian/Ubuntu, `sudo yum install libcurl-devel` on RHEL/CentOS). On platforms without pre-built wheels or complex build environments (like some ARM systems), you may need to manually compile `curl-impersonate` first, then set `LD_LIBRARY_PATH` or equivalent before installing `curl-cffi`.

Upgrade

Version history

0.16.2latest on PyPI · released Aug 25, 2026

Audit

Dependencies

cffirequiredCore dependency for C Foreign Function Interface.

certifirequiredProvides a curated list of trusted CA certificates for SSL/TLS verification.

libcurlrequiredUnderlying C library; pre-compiled wheels are provided, but manual compilation might be needed on unsupported platforms.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lexiforest/curl_cffi ↗

packagehttps://pypi.org/project/curl-cffi/ ↗