tls-client-python

维护边界： Go 引擎同步自上游，本项目的 Python/CFFI 扩展及冲突保留规则见 UPSTREAM_SYNC.md。日常修改请勿直接改动上游归属区域。

Requests 兼容层： 请求 API 的完整清单、兼容契约与生成式约束见 docs/REQUESTS_API.md。静态扫描入口： python3 -m tls_client._static_scan。

CFFI-based, high-performance Python binding for tls-client — drop-in compatible with requests and Python-Tls-Client.

What is TLS Fingerprinting?

Some people think it is enough to change the user-agent header of a request to let the server think that the client requesting a resource is a specific browser. Nowadays this is not enough, because the server might use a technique to detect the client browser which is called TLS Fingerprinting.

For a deep dive, see this excellent article on TLS fingerprinting.

✨ Features

macOS TCP fingerprinting: macOS derives TCP MSS during connect and rejects TCP_MAXSEG in the pre-connect socket hook. The MSS hint is therefore skipped on macOS; TTL, receive-window tuning, and TLS/HTTP fingerprints remain active. This avoids MSS(1460): invalid argument on macOS 26 and earlier.

📦 Installation

pip install tls-client-python

Pre-compiled binaries are included for 12 platforms (plus a macOS universal2 wheel) — no Go toolchain required.

Requirements: Python 3.6+

🚀 Quick Start

from tls_client import Session

# Create a session with Chrome 146 fingerprint
session = Session(client_identifier="chrome_146", verify=False)

# GET request
resp = session.get("https://tls.browserleaks.com/json")
print(resp.status_code)
print(resp.text)

# POST request
resp = session.post("https://tools.scrapfly.io/api/fp/ja3")
data = resp.json()
print(resp.status_code)
print(data)


# Context Manager
with Session(client_identifier="firefox_148") as session:
    resp = session.get("https://tls.browserleaks.com/json")
    print(resp.status_code)
    print(resp.text)


# Async Usage
import asyncio
from tls_client import AsyncSession

async def main():
    async with AsyncSession(client_identifier="firefox_148") as s:
        resp = await s.get("https://tls.browserleaks.com/json")
        print(resp.status_code)
        print(resp.json())

asyncio.run(main())

Requests-compatible API

The synchronous API implements Requests-style request preparation, session state, redirects, cookies, hooks, exceptions, and response objects without depending on the Requests package. Network transport remains the native tls-client engine:

import tls_client

response = tls_client.get(
    "https://example.com/api",
    params={"page": 1},
    headers={"Accept": "application/json"},
    timeout=(3.05, 30),
)
response.raise_for_status()
print(response.json())

with tls_client.Session(client_identifier="chrome_146") as session:
    session.headers.update({"Authorization": "Bearer token"})
    response = session.post(
        "https://example.com/upload",
        files={"file": ("data.txt", b"payload")},
        hooks={"response": lambda r, *args, **kwargs: r},
    )

Request, PreparedRequest, Response, exceptions, codes, cookies, auth, adapters, structures, and all top-level HTTP helpers follow the commonly used Requests API. The previous low-level objects remain available as NativeSession, NativeResponse, and TLSRequest. stream=True exposes the normal Requests iteration API, but the current native ABI buffers the response before Python receives it. A string verify value enables verification with system roots; passing a custom CA bundle through the C ABI is not yet supported.

🖥️ Supported Platforms

Pre-compiled native libraries are bundled for these platforms:

The correct binary is automatically selected at runtime. Override via TLS_CLIENT_LIB environment variable.

🎭 Supported Browser Profiles

The complete, runtime-validated list is exported as tls_client.SUPPORTED_CLIENT_IDENTIFIERS. It is also used for IDE/type checking through ClientIdentifiers.

🌐 Chrome — 79 Profiles (captured 99–153 + hand-written)

The full Chrome range 99 through 153 is available, recovered from live handshakes rather than hand-transcribed. Every major ships as both chrome_<major> and chrome_<major>_PSK:

The captures pin the real per-version cipher list, extension order, supported groups, signature algorithms, JA3/JA4 and HTTP/2 Akamai fingerprint — so chrome_111, chrome_121, chrome_137 etc. reproduce the wire bytes of that exact release, including the per-milestone extension-order reshuffles.

Hand-written profiles with PSK / Post-Quantum / trust-anchor refinements (chrome_116_PSK_PQ, chrome_130_PSK, chrome_144, chrome_146, chrome_150, chrome_152, …) remain authoritative where they exist.

🦊 Firefox — 16 Profiles

🍏 Safari — 10 Profiles

🦁 Brave — 2 Profiles

🎭 Opera — 3 Profiles

🤖 OkHttp (Android) — 7 Profiles

📱 Mobile / App SDKs — 16 Profiles

☁️ Cloudflare-specific — 1 Profile

🔧 Advanced Usage

Full TLS controls at the top-level Session

tls_client.Session is Requests-compatible, but its public constructor keeps the complete native TLS signature. IDE completion and inspect.signature() therefore expose fingerprint, protocol, socket, proxy, certificate, cookie, pool, and debug controls instead of showing only Requests arguments:

import inspect
import tls_client

print(inspect.signature(tls_client.Session))
session = tls_client.Session(
    client_identifier="chrome_152",
    force_http1=True,
    disable_http3=True,
    random_tls_extension_order=False,
    tcp_mss=1460,
    tcp_ttl=64,
    max_connections_per_host=32,
    with_debug=True,
)

The same TLS keyword names are accepted by Requests-style calls (get, post, request, and execute_request) for per-request overrides.

Unknown browser/fingerprint identifiers fail immediately with ValueError. Use SUPPORTED_CLIENT_IDENTIFIERS to validate user input before creating a session.

Custom TLS Client (Full Control)

Set custom_tls_client with up to 26 fields to bypass client_identifier entirely:

session = Session(custom_tls_client={
    "ja3_string": "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0",
    "h2_settings": {"HEADER_TABLE_SIZE": 65536, "MAX_CONCURRENT_STREAMS": 1000},
    "h2_settings_order": ["HEADER_TABLE_SIZE", "MAX_CONCURRENT_STREAMS"],
    "pseudo_header_order": [":method", ":authority", ":scheme", ":path"],
    "connection_flow": 1048576,
    "key_share_curves": ["X25519", "P256"],
    "alpn_protocols": ["h2", "http/1.1"],
    "supported_versions": ["1.3", "1.2"],
    "stream_id": 3,
})

Certificate Pinning

session = Session(
    certificate_pinning_hosts={
        "example.com": ["sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="]
    }
)

Client Certificates (mTLS)

session = Session(
    client_certificates=[{
        "cert_pem": open("client.crt", "rb").read(),
        "key_pem": open("client.key", "rb").read(),
    }]
)

Fingerprint Presets (Coherent Browser Bundles)

A preset bundles the engine TLS profile, the per-OS coherent header block (UA + Client Hints), the destination-aware header orders, the extension-shuffle policy and the OS TCP fingerprint in one line:

from tls_client import Session
from tls_client.fingerprints import apply, list_presets

print(len(list_presets()))            # 391 presets

session = Session()
apply(session, "chrome_150_windows")  # or chrome_99_linux, chrome_153_ios, ...
session.get("https://tls.peet.ws/api/all")

All 55 captured Chrome majors (99–153) ship as chrome_<major>_base, chrome_<major>_windows, _macos, _linux, _android, _ios, plus a bare chrome_<major> alias for the Windows variant — and each per-OS variant derives a platform-coherent UA and TCP fingerprint (Windows TTL=128/window=64240, Linux/macOS TTL=64/window=65535, etc.). header_order_for_dest(dest) returns the header template for a Sec-Fetch-Dest value.

Or directly: Session(fingerprint="chrome_150_windows"). Custom presets are plain JSON with optional based_on inheritance:

from tls_client.fingerprints import load_preset_file
load_preset_file("my_chrome.json")     # {"name": ..., "based_on": "chrome_152_windows", ...}

Request Contexts (Sec-Fetch-*, Client Hints, Priority)

Describe how the request was initiated and the coherent header set is derived (opt-in — without context= nothing changes):

from tls_client.context import RequestContext

session.get(url, context=RequestContext.navigation(url, referrer=page_url))
session.post(api, context=RequestContext.xhr(api))
session.get(img, context=RequestContext.image(img))

Trust Anchors (Chrome 152+, ABI 2) and ECH

session = Session(custom_tls_client={
    "ja3_string": "...",
    "trust_anchors_payload": "0009080102030405060708",  # hex of the 0xCA34 payload
})

# Automatic ECH resolution over DoH (RFC 9460), cached per host:
from tls_client import ech
payload = ech.resolve("tls.peet.ws")
session = Session(custom_tls_client={
    "ja3_string": "...",
    "ech_candidate_payloads": ech.to_candidate_payloads(payload),
})

TLS_CLIENT_DOH_ENDPOINT overrides the DoH server (e.g. https://dns.alidns.com/resolve) — useful on networks where cloudflare-dns.com is unreachable.

TLS Debugging (Keylog) and Custom CA (ABI 2)

session = Session(
    tls_keylog_path="keylog.txt",      # Wireshark TLS secrets
    root_ca_pem=open("corp-ca.pem", "rb").read(),
    disable_session_tickets=True,
)

Deep Fingerprint Control (ABI 3)

Fine-grained, byte-level control over the handshake and the socket:

session = Session(
    client_identifier="chrome_150",

    # Chromium shuffles the ClientHello extension order on *every*
    # handshake (unseeded), pinning GREASE / padding / pre_shared_key.
    #   0 = off (captured order)   1 = chrome
    #   2 = all extensions         3 = prefix (first N stay fixed)
    extension_permute_mode=1,
    extension_permute_prefix=0,     # only meaningful when mode=3

    # Suppress RFC 7540 PRIORITY frames / the HEADERS priority flag.
    h2_disable_priority_frames=False,

    # Pick the header order from the request's Sec-Fetch-Dest instead of
    # using one fixed order for every request.
    header_order_by_dest=True,
    header_order_dest=None,         # None = infer from Sec-Fetch-Dest

    # Deep TCP fingerprint. -1 (the default) leaves the profile's own
    # value untouched; 0 is a *real* value (DF cleared / TOS 0 / Nagle off).
    tcp_dont_fragment=-1,           # -1 unset · 0 clear DF · 1 set DF
    tcp_tos=-1,                     # -1 unset · 0..255
    tcp_no_delay=-1,                # -1 unset · 0 off · 1 on
    tcp_window_clamp=0,             # 0 unset · Linux TCP_WINDOW_CLAMP
    tcp_ip_id_mode="",              # "" unset · "random" · "zero" · "incremental"
)

Every parameter can also be set per request. On a shared library older than ABI 3 these degrade to their defaults with a one-time RuntimeWarning instead of failing the request — rebuild the native library to enable them.

Presets bundle all of the above automatically:

from tls_client.fingerprints import apply

session = Session()
apply(session, "chrome_150_linux")   # identifier + headers + permute + TCP

WebSocket (TLS-fingerprinted)

WebSocket connections reuse the same TLS fingerprint, connection pool and header ordering as regular requests. The handshake is forced to HTTP/1.1 (as the WebSocket upgrade requires it).

from tls_client import WebSocket, TEXT, BINARY

# The fingerprint client is created from client_identifier (HTTP/1.1 enforced).
ws = WebSocket(url="wss://echo.websocket.events", client_identifier="chrome_131")

conn = ws.connect()                       # blocking handshake
conn.send_text("hello")                   # UTF-8 text frame
conn.send_binary(b"\x00\x01\x02")         # binary frame

message_type, data = conn.read_message()  # (TEXT=1, b"...") — blocks

conn.close()
ws.close()

read_message() returns a (message_type, data) tuple where message_type is one of TEXT/BINARY/CLOSE/PING/PONG; it returns None on a clean close. Handshake headers and their wire order are controllable:

ws = WebSocket(
    url="wss://example.com/ws",
    client_identifier="firefox_148",
    headers={"User-Agent": "MyBot/1.0", "Origin": "https://example.com"},
    header_order=["host", "upgrade", "connection", "user-agent"],
    handshake_timeout_milliseconds=10000,
)

Build Tiers

A single full-fidelity build ships in each wheel — QUIC/HTTP-3 enabled and the complete profile catalogue (there are no lite/nano tiers).

TLS_CLIENT_LIB=/path/to/tls-client.so   # optional: override the library path

TLS_CLIENT_LIB overrides the path entirely; by default the loader picks the bundled native binary for the current OS/arch.

Engine-Level HTTP/2 Realism (ABI 2.1)

session = Session(
    hpack_indexing_policy="chrome",   # Chromium HPACK indexing behaviour
    h2_max_data_frame_size=14000,     # cap each DATA frame payload
    preface_ping_idle_ms=10000,       # PING before reuse after >=10s idle
    cookie_crumb=True,                # one Cookie field per cookie-pair
)

cookie_crumb splits the Cookie header into one field per cookie-pair on the wire (Chromium "crumble") — observable as multiple cookie: fields by HTTP/2 servers.

Stream Response to Disk

resp = session.stream_to_file(
    "GET", "https://tls.browserleaks.com/",
    output_path="/tmp/image.png"
)
print(resp.status_code)  # response metadata still available

Per-Request Overrides

All Session constructor parameters can be overridden per request:

s = Session(client_identifier="chrome_146")
# Override fingerprint for a single request
resp = s.get("https://tls.browserleaks.com/json", client_identifier="firefox_148")

🔬 Architecture

📚 API Reference

Session

Response

🔗 Credits

This project is a Python binding for bogdanfinn/tls-client, which itself is built upon:

• Carcraftz/fhttp
• Carcraftz/utls
• refraction-networking/utls

The byte-exact fingerprint layer also draws on two Go fingerprinting projects whose captured-clienthello techniques were studied as references:

• enetx/surf — full utls.ClientHelloSpec profiles (trust-anchor 0xCA34, ML-DSA/ML-KEM post-quantum, GREASE) for Chrome/Firefox.
• httpcloak — raw ClientHello / PSK-resumption replay, per-header HPACK representation and the high-entropy Client Hints model.

Thanks to the authors of all of the above for their open work.

📄 License

MIT — see LICENSE.