curl-impersonate

curl-impersonate is a specialized build of curl designed to send HTTP requests that mimic the behavior of modern web browsers. This helps in bypassing anti-bot protections that rely on TLS fingerprints and HTTP/2 settings.

It can be used in two primary ways:

1. As a command-line tool: Operates similarly to the standard curl CLI.
2. As a library: Can be integrated into applications as a replacement for the standard libcurl.

Docker images are available on Docker Hub. There are two distinct versions based on the target browser type:

1. Firefox version (-ff): Used for impersonating Firefox.
2. Chrome version (-chrome): Used for impersonating Chrome, Edge, and Safari.

Both images are based on Alpine Linux and include the binaries and all wrapper scripts.

# Firefox version, Alpine Linux
docker pull lwthiker/curl-impersonate:0.6-ff
docker run --rm lwthiker/curl-impersonate:0.6-ff curl_ff109 https://www.wikipedia.org

# Chrome version, Alpine Linux
docker pull lwthiker/curl-impersonate:0.6-chrome
docker run --rm lwthiker/curl-impersonate:0.6-chrome curl_chrome110 https://www.wikipedia.org

Pre-compiled binaries for Linux and macOS (Intel) are available on the GitHub releases page.

Prerequisites

You must install nss (the TLS library used by Firefox) and ca-certificates, and ensure zlib is present on your system.

Installation commands by OS:

• Ubuntu: sudo apt install libnss3 nss-plugin-pem ca-certificates
• Red Hat/Fedora/CentOS: yum install nss nss-pem ca-certificates
• Archlinux: pacman -S nss ca-certificates
• macOS: brew install nss ca-certificates

Certificate Verification on Linux

Pre-compiled Linux binaries are built for Ubuntu. If you encounter certificate verification errors on other distributions, manually specify the CA certificate path using the --cacert flag:

curl_chrome116 https://www.wikipedia.org --cacert /etc/ssl/certs/ca-bundle.crt

To use libcurl-impersonate in PHP on macOS, rename the library to match the expected libcurl filename and use DYLD_LIBRARY_PATH to point to its location.

1. Rename libcurl-impersonate-chrome.dylib to libcurl.4.dylib.
2. Place the renamed file in a directory (e.g., /usr/local/lib).
3. Run your PHP script with DYLD_LIBRARY_PATH set to that directory: DYLD_LIBRARY_PATH=/usr/local/lib php -r 'print_r(curl_version());'

If successful, curl_version() will report [ssl_version] => BoringSSL.

Arch Linux users can use the Arch User Repository (AUR) to install curl-impersonate:

• Pre-compiled packages: curl-impersonate-bin or libcurl-impersonate-bin.
• Build from source: curl-impersonate-chrome or curl-impersonate-firefox.

You can run curl-impersonate binaries directly, but doing so will not produce the correct TLS and HTTP/2 signatures required for browser impersonation. To achieve an identical signature to a specific browser version, you must use the provided wrapper scripts (e.g., curl_chrome104).

Wrapper scripts automatically pass the necessary flags to the underlying binary to match the browser's signature. You can still append additional standard curl flags to these wrapper scripts, but be cautious of flags that modify the TLS signature.

On Linux, you can inject libcurl-impersonate.so into an existing application that uses libcurl without modifying its source code. By setting the CURL_IMPERSONATE environment variable, curl_easy_impersonate() is automatically called whenever the application creates a new curl handle via curl_easy_init() or resets one via curl_easy_reset().

Note: This method does NOT work for the curl command-line tool itself, as the tool overrides TLS settings. Use the provided wrapper scripts for the CLI tool instead.

To disable the built-in HTTP headers and provide your own, set CURL_IMPERSONATE_HEADERS=no.

For CentOS, Fedora, or Amazon Linux, follow these steps:

1. Install Dependencies

Install core build tools:

yum groupinstall "Development Tools"
yum groupinstall "C Development Tools and Libraries" # Fedora only
yum install cmake3 python3 python3-pip
# Install Ninja
yum install ninja-build
# OR
pip3 install ninja

For the Firefox version:

yum install nss nss-pem
pip3 install gyp-next

For the Chrome version:

yum install golang

2. Build and Install

After installing dependencies, follow the same build steps used for Ubuntu (cloning the repo, running ../configure, and using make).

Unofficial Homebrew receipts for macOS (supporting Chrome only) can be installed using the shakacode/brew tap.

brew tap shakacode/brew
brew install curl-impersonate

curl-impersonate is supported on Linux and macOS. For installation instructions, refer to the main repository page. The project provides two distinct versions depending on the browser fingerprint you wish to emulate:

1. Chrome version: A modified curl binary and libcurl library that impersonates Chrome, Edge, and Safari. It uses BoringSSL (Chrome's TLS library) and includes patched TLS extensions and modified HTTP/2 settings.
2. Firefox version: A modified curl binary that impersonates Firefox. It uses NSS (Mozilla's TLS library).

Windows Support: For Windows users, use the separate curl-impersonate-win project.

To use libcurl-impersonate in PHP on Linux, you must patch the library's SONAME and then use LD_PRELOAD to inject it at runtime. This allows PHP to use the impersonating library instead of the system's default libcurl.

1. Patch the library to change its SONAME: patchelf --set-soname libcurl.so.4 /path/to/libcurl-impersonate-chrome.so

2. Run your PHP script using LD_PRELOAD and the CURL_IMPERSONATE environment variable: LD_PRELOAD=/path/to/libcurl-impersonate-chrome.so CURL_IMPERSONATE=chrome101 php -r 'print_r(curl_version());'

If successful, curl_version() will report [ssl_version] => BoringSSL (for Chrome versions) or [ssl_version] => NSS (for Firefox versions).