libcurl ffi bindings for Python, with impersonation support
Project description
curl_cffi
Python binding for curl-impersonate via CFFI.
Unlike other pure python http clients like httpx
or requests
, this package can
impersonate browsers' TLS signatures or JA3 fingerprints. If you are blocked by some
website for no obvious reason, you can give this package a try.
Note on Chrome 110+ JA3 fingerprints
Chrome introduces ClientHello permutation in version 110, which means the order of
extensions will be random, thus JA3 fingerprints will be random. So, when comparing
JA3 fingerprints of curl_cffi
and a browser, they may differ. However, this does not
mean that TLS fingerprints will not be a problem, ClientHello extension order is just
one factor of how servers can tell automated requests from browsers.
See more from this article and curl-impersonate notes
Install
pip install --upgrade curl_cffi
This should work for Linux(x86_64/aarch64), macOS(Intel/Apple Silicon), Windows(amd64).
If it does not work, you may need to compile and install curl-impersonate
first.
Usage
requests/httpx
-like API:
from curl_cffi import requests
# Notice the impersonate parameter
r = requests.get("https://tls.browserleaks.com/json", impersonate="chrome101")
print(r.json())
# output: {'ja3_hash': '53ff64ddf993ca882b70e1c82af5da49'
# the fingerprint should be the same as target browser
# proxies are supported
proxies = {"https": "http://localhost:3128"}
r = requests.get("https://tls.browserleaks.com/json", impersonate="chrome101", proxies=proxies)
# socks proxies are also supported
proxies = {"https": "socks://localhost:3128"}
r = requests.get("https://tls.browserleaks.com/json", impersonate="chrome101", proxies=proxies)
Sessions
# sessions are supported
s = requests.Session()
# httpbin is a http test website
s.get("https://httpbin.org/cookies/set/foo/bar")
print(s.cookies)
# <Cookies[<Cookie foo=bar for httpbin.org />]>
r = s.get("https://httpbin.org/cookies")
print(r.json())
# {'cookies': {'foo': 'bar'}}
Supported impersonate versions:
- chrome99
- chrome100
- chrome101
- chrome104
- chrome107
- chrome110
- chrome99_android
- edge99
- edge101
- safari15_3
- safari15_5
Alternatively, you can use the low-level curl-like API:
from curl_cffi import Curl, CurlOpt
from io import BytesIO
buffer = BytesIO()
c = Curl()
c.setopt(CurlOpt.URL, b'https://tls.browserleaks.com/json')
c.setopt(CurlOpt.WRITEDATA, buffer)
c.impersonate("chrome101")
c.perform()
c.close()
body = buffer.getvalue()
print(body.decode())
See example.py
or tests/
for more examples.
API
Requests: almost the same as requests.
Curl object:
setopt(CurlOpt, value)
: Sets curl options as incurl_easy_setopt
perform()
: Performs curl request, as incurl_easy_perform
getinfo(CurlInfo)
: Gets information in response after curl perform, as incurl_easy_getinfo
close()
: Closes and cleans up the curl object, as incurl_easy_cleanup
Enum values to be used with setopt
and getinfo
, and can be accessed from CurlOpt
and CurlInfo
.
Trouble Shooting
Pyinstaller ModuleNotFoundError: No module named '_cffi_backend'
You need to tell pyinstaller to pack cffi and data files inside the package:
pyinstaller -F .\example.py --hidden-import=_cffi_backend --collect-all curl_cffi
Using https proxy, error: OPENSSL_internal:WRONG_VERSION_NUMBER
You are messing up https-over-http proxy and https-over-https proxy, for most cases, you
should change {"https": "https://localhost:3128"}
to {"https": "http://localhost:3128"}
.
Note the protocol in the url for https proxy is http
not https
.
See this issue for a detailed explaination.
Current Status
This implementation is very hacky now, but it works for most common systems.
When people installing other python curl bindings, like pycurl
, they often face
compiling issues or OpenSSL issues, so I really hope that this package can be distributed
as a compiled binary package, uses would be able to use it by a simple pip install
, no
more compile errors.
For now, I just download the pre-compiled libcurl-impersonate
from github and build a
bdist wheel, which is a binary package format used by PyPI, and upload it. However, the
right way is to download curl and curl-impersonate sources on our side and compile them
all together.
Help wanted!
TODOs:
- Write docs.
- Binary package for macOS(Intel/AppleSilicon) and Windows.
- Support musllinux(alpine) bdist by building from source.
- Exclude the curl headers from source, download them when building.
- Update curl header files and constants via scripts.
- Implement
requests.Session/httpx.Client
. - Create ABI3 wheels to reduce package size and build time.
- Set default headers as in curl-impersonate wrapper scripts.
- Support stream in asyncio mode
Change Log
-
0.5.0
- Added asyncio support
-
0.4.0
- Removed c shim callback function, use cffi native callback function
-
0.3.6
- Updated to curl-impersonate v0.5.4, supported chrome107 and chrome110
-
0.3.0, copied more code from
httpx
to support session- Add
requests.Session
- Breaking change:
Response.cookies
changed fromhttp.cookies.SimpleCookie
tocurl_cffi.requests.Cookies
- Using ABI3 wheels to reduce package size.
- Add
Acknowledgement
- This package was originally forked from https://github.com/multippt/python_curl_cffi , which is under the MIT license.
- headers/cookies files are copied from 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for curl_cffi-0.5.4-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2d526d4137261725bc0a3255b3b58253edb39c377a761ec1beeecd185e68fe6b |
|
MD5 | fa1cddaa0a8dfca55c78e40a5cea020d |
|
BLAKE2b-256 | 32d01926e3c785146274df48ec7a3ede0255bdbc1c9f281657915cfca255ebd8 |
Hashes for curl_cffi-0.5.4-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f73a7b981eabaee0631068f7cce1a23335f9b7672339ed7f457ab817c4fb8d27 |
|
MD5 | fee9c3e1174536f501615352a6ab1b14 |
|
BLAKE2b-256 | f64418d496196bded0f8d41c57e7d2b2d862b5ff5c407ea2c2fe0e5dc8bf61b4 |
Hashes for curl_cffi-0.5.4-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1022974826daa8327eee3592298943671389168bb27e3b82227f47bfb01e9819 |
|
MD5 | 4890b0b7b63d9c8bcf6174e33757278d |
|
BLAKE2b-256 | 77c5606ae26a89f68478204a07b9861c6d02929227af2711fdf266e792c99fde |
Hashes for curl_cffi-0.5.4-cp37-abi3-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 868f50f7a62309448b9973efd4e19aec5980911f45b7b690670ef02b4d264507 |
|
MD5 | 71ec593d4ae4f8545992d71d0948ec28 |
|
BLAKE2b-256 | 8e20e8767d0937ff55ffd1cce8165e3a95d0ce0e9c96cb52ef7c5ef2fe04cb6e |
Hashes for curl_cffi-0.5.4-cp37-abi3-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 227394058080866fc4ba5e968738eeb059945d88900601bae1d34767be851c85 |
|
MD5 | 8dd3e6b2a47c6c0b9346c0d27ba05f3c |
|
BLAKE2b-256 | 0c330a16965e963a7aa46e9edd6420a6f80e24fa348fc8f84017c8b0e4a84314 |