curl-impersonate

A special build of curl that can impersonate the four major browsers: Chrome, Edge, Safari and Firefox. curl-impersonate is able to perform TLS and HTTP handshakes that are identical to that of a real browser.

curl-impersonate can be used either as a command line tool, similar to the regular curl, or as a library that can be integrated instead of the regular libcurl. See docs.

Documentation

Documentation is available at https://curl-impersonate.readthedocs.io/

Why?

When you use an HTTP client with a TLS website, it first performs a TLS handshake. The first message of that handshake is called Client Hello. The Client Hello message that most HTTP clients and libraries produce differs drastically from that of a real browser.

If the server uses HTTP/2, then in addition to the TLS handshake there is also an HTTP/2 handshake where various settings are exchanged. The settings that most HTTP clients and libraries use differ as well from those of any real browsers.

For these reasons, some web services use the TLS and HTTP handshakes to fingerprint which client is accessing them, and then present different content for different clients. These methods are known as TLS fingerprinting and HTTP/2 fingerprinting respectively. Their widespread use has led to the web becoming less open, less private and much more restrictive towards specific web clients.

With the modified curl in this repository, the TLS and HTTP handshakes look exactly like those of a real browser.

How?

To make this work, curl was patched significantly to resemble a browser. Specifically, The modifications that were needed to make this work:

• Compiling with BoringSSL, Google's TLS library, which is used by Chrome and Safari.
• Modifying the way curl configures various TLS extensions and SSL options.
• Adding support for new TLS extensions.
• Changing the settings that curl uses for its HTTP/2 connections.
• Running curl with some non-default flags, for example --ciphers, --curves and some -H headers.

The resulting curl looks, from a network perspective, identical to a real browser.

Read the original technical description in the blog posts: part a, part b. Much more has been added since then, but you get the general ideas :P.

Supported browsers

The following browsers can be impersonated. For a full list of browser profiles, visit the docs.

Browser	Version	OS	Target name	Wrapper script	H3 fingerprints
	99	Windows 10	chrome99	curl_chrome99
	100	Windows 10	chrome100	curl_chrome100
	101	Windows 10	chrome101	curl_chrome101
	104	Windows 10	chrome104	curl_chrome104
	107	Windows 10	chrome107	curl_chrome107
	110	Windows 10	chrome110	curl_chrome110
	116	Windows 10	chrome116	curl_chrome116
	119	macOS Sonoma	chrome119	curl_chrome119
	120	macOS Sonoma	chrome120	curl_chrome120
	123	macOS Sonoma	chrome123	curl_chrome123
	124	macOS Sonoma	chrome124	curl_chrome124
	131	macOS Sonoma	chrome131	curl_chrome131
	133	macOS Sequoia	chrome133a	curl_chrome133a
	136	macOS Sequoia	chrome136	curl_chrome136
	142	macOS Tahoe	chrome142	curl_chrome142
	145	macOS Tahoe	chrome145	curl_chrome145	✅
	146	macOS Tahoe	chrome146	curl_chrome146	✅
	99	Android 12	chrome99_android	curl_chrome99_android
	131	Android 14	chrome131_android	curl_chrome131_android
	99	Windows 10	edge99	curl_edge99
	101	Windows 10	edge101	curl_edge101
	15.3	macOS Big Sur	safari153	curl_safari153
	15.5	macOS Monterey	safari155	curl_safari155
	17.0	macOS Sonoma	safari170	curl_safari170
	17.2	iOS 17.2	safari172_ios	curl_safari172_ios
	18.0	macOS Sequoia	safari180	curl_safari180
	18.0	iOS 18.0	safari180_ios	curl_safari184_ios
	18.4	macOS Sequoia	safari184	curl_safari184
	18.4	iOS 18.4	safari184_ios	curl_safari180_ios
	26.0	macOS Tahoe	safari260	curl_safari260
	26.0	iOS 26.0	safari260_ios	curl_safari260_ios
	26.0.1	macOS Tahoe	safari2601	curl_safari2601
	133.0	macOS Sonoma	firefox133	curl_firefox133
	135.0	macOS Sonoma	firefox135	curl_firefox135
	144.0	macOS Tahoe	firefox144	curl_firefox144
	147.0	macOS Tahoe	firefox147	curl_firefox147	✅
	14.5	macOS Sonoma	tor145	curl_tor145

Notes:

1. Chromium-based browsers all share the same fingerprints, except for the User-Agent header and sec-ch-ua-platform header. They will not be updated unless this assumption changed. Use your own header if you need to impersonate Edge, Chrome Android etc.
2. The original Safari fingerprints in the upstream fork are not correct.
3. 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.

This list is also available in the browsers.json file.() Needs to be updated.

Install

The simplest way is to download the prebuilt binaries from the release page. If you want to build by yourself, please refer to INSTALL.md and docs/install.rst.

You can also use the following docker images:

• lexiforest/curl-impersonate
• lexiforest/curl-impersonate:alpine

Basic usage

For each supported browser there is a wrapper script that launches curl-impersonate with all the needed headers and flags. For example:

curl_chrome123 https://www.example.com

You can add command line flags and they will be passed on to curl. However, some flags change curl's TLS signature which may cause it to be detected.

To check the fingerprints are correct:

curl_firefox133 https://tls.browserleaks.com/json

Please note that the wrapper scripts use a default set of HTTP headers. If you want to change these headers, you may want to modify the wrapper scripts to fit your own purpose.

See the docs for more options, including using libcurl-impersonate as a library.

Repository Contents

This repository contains these folders:

• patches - Patches for building curl-impersonate.
  • curl.patch - The main patch that makes curl use the same TLS extensions as browsers. Also makes curl compile statically with libnghttp2 etc.
  • boringssl.patch - The boringssl patch that tweaks boringssl behaviors to the same as browsers.
• bin - Shortcut scripts for easier use.
  • curl_chrome110, curl_chrome124 - Wrapper scripts that launch curl-impersonate with the correct flags.
• win - Scripts for building the Windows version of curl-impersonate, which is quite different from *nix.
  • win/bin - Shortcut scripts for easier use on Windows.
• zigshim - We use the awesome zig toolchain to bring curl-impersonate to more archs on Linux.
• docker - Debian and alpine dockerfiles for this project.

Other files of interest:

• tests/signatures - YAML database of known browser signatures that can be impersonated.

Contributing

If you'd like to help, please check out the open issues in the origional repo and open issues here. You can open a pull request with your changes. Note that some of the upstream issues have been fixed.

This repository contains the build process for curl-impersonate. The actual patches to curl are maintained in a separate repository forked from lwthiker's fork of the upstream curl. The changes are maintained in the impersonate-chrome branch.

You may also need the forked and patched BoringSSL.

Acknowledgements

• Special thanks to @bjia56 for making cross compiling possible.
• Special thanks to @smaug2309 and @afulsamet for bring back the Windows build.
• Special thanks to @penumbra-x for the boringssl patch on firefox.

Sponsors

Bypass Cloudflare with API

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

Hyper Solutions

TLS fingerprinting alone isn't enough for modern bot protection. Hyper Solutions 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 | 📖 Docs | 💬 Discord

Recall.ai - API for meeting recordings

If you’re looking for a meeting recording API, consider checking out Recall.ai, an API that records Zoom, Google Meet, Microsoft Teams, in-person meetings, and more.

Residential Proxies

Thordata: A reliable and cost-effective proxy service provider. One-click collection of public network data, providing enterprises and developers with stable, efficient, and compliant global proxy IP services. Register for a free trial of residential proxies and receive 2000 free SERP API calls.