tls-client-python

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

PyPI version Python License: MIT

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

Category Details
🔐 TLS Fingerprinting Impersonate Chrome, Firefox, Safari, Brave, Opera, OkHttp & more
🌐 Protocol Support HTTP/1.1, HTTP/2 (h2), HTTP/3 (QUIC) with automatic negotiation
⚡ Protocol Racing Chrome-style Happy Eyeballs for HTTP/2 vs HTTP/3
📋 Header Ordering Control the exact order of HTTP headers per request
🔒 Certificate Pinning Pin server certificates for enhanced security
🍪 Cookie Jar Built-in cookie handling with customisable jar
🚇 Proxy Support HTTP and SOCKS5 proxies with CONNECT auth
🔀 Redirect Control Choose whether to follow redirects per request
📊 Bandwidth Tracking Monitor upload/download bytes in real time
🔄 sync/Async Session + AsyncSession
🛡️ Panic-proof All Go panics caught and surfaced as Python exceptions
⚙️ Custom TLS Full 26-field custom TLS client configuration

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 9 platforms — 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:

OS Architecture Binary
Windows x86-64 tls-client-windows-amd64.dll
Windows x86 (32-bit) tls-client-windows-386.dll
macOS x86-64 tls-client-darwin-amd64.dylib
macOS ARM64 (Apple Silicon) tls-client-darwin-arm64.dylib
Linux x86-64 (glibc) tls-client-linux-amd64.so
Linux x86 (32-bit, glibc) tls-client-linux-386.so
Linux ARM64 tls-client-linux-arm64.so
Linux ARMv7 tls-client-linux-arm.so
Alpine Linux x86-64 (musl) tls-client-alpine-amd64.so

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

🎭 Supported Browser Profiles — 79 Identifiers

🌐 Chrome — 24 Profiles

Identifier Notes
chrome_103 — chrome_112 Chrome Stable 103–112
chrome_116_PSK Chrome 116 with PSK key exchange
chrome_116_PSK_PQ Chrome 116 with PSK + Post-Quantum
chrome_117 Chrome 117
chrome_120 Chrome 120
chrome_124 Chrome 124
chrome_130_PSK Chrome 130 with PSK
chrome_131 · chrome_131_PSK Chrome 131 (standard & PSK)
chrome_133 · chrome_133_PSK Chrome 133 (standard & PSK)
chrome_144 · chrome_144_PSK Chrome 144 (standard & PSK)
chrome_146 · chrome_146_PSK Chrome 146 — default (standard & PSK)

🦊 Firefox — 16 Profiles

Identifier Notes
firefox_102 · firefox_104 · firefox_105 · firefox_106 Firefox 102–106
firefox_108 · firefox_110 Firefox 108 · 110
firefox_117 · firefox_120 · firefox_123 Firefox 117–123
firefox_132 · firefox_133 · firefox_135 Firefox 132–135
firefox_146_PSK Firefox 146 with PSK
firefox_147 · firefox_147_PSK Firefox 147 (standard & PSK)
firefox_148 Firefox 148

🍏 Safari — 10 Profiles

Identifier Device
safari_15_6_1 Safari 15.6.1 (macOS)
safari_16_0 Safari 16.0 (macOS)
safari_ipad_15_6 Safari 15.6 (iPadOS)
safari_ios_15_5 · safari_ios_15_6 Safari iOS 15.5–15.6
safari_ios_16_0 · safari_ios_17_0 Safari iOS 16 · 17
safari_ios_18_0 · safari_ios_18_5 Safari iOS 18 · 18.5
safari_ios_26_0 Safari iOS 26

🦁 Brave — 2 Profiles

Identifier Notes
brave_146 Brave Browser 146
brave_146_PSK Brave 146 with PSK

🎭 Opera — 3 Profiles

Identifier
opera_89 · opera_90 · opera_91

🤖 OkHttp (Android) — 7 Profiles

Identifier
okhttp4_android_7 — okhttp4_android_13

📱 Mobile / App SDKs — 16 Profiles

Category Identifiers
Zalando zalando_android_mobile · zalando_ios_mobile
Nike nike_ios_mobile · nike_android_mobile
MMS mms_ios · mms_ios_1 · mms_ios_2 · mms_ios_3
Mesh mesh_ios · mesh_ios_1 · mesh_ios_2 · mesh_android · mesh_android_1 · mesh_android_2
Confirmed confirmed_ios · confirmed_android

☁️ Cloudflare-specific — 1 Profile

Identifier Notes
cloudscraper Custom profile tuned for Cloudflare-protected sites

🔧 Advanced Usage

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(),
    }]
)

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

Layer Technology
Go Engine bogdanfinn/tls-client compiled as C shared library (-buildmode=c-shared)
FFI Boundary Raw C structs via CFFI — no JSON serialization overhead
Memory Safety ffi.gc(resp, FreeResponse) — Go panics surfaced as RuntimeError
Python API requests-style Session, Response, AsyncSession

📚 API Reference

Session

Method Description
get(url, **kwargs) HTTP GET
post(url, **kwargs) HTTP POST
put(url, **kwargs) HTTP PUT
delete(url, **kwargs) HTTP DELETE
head(url, **kwargs) HTTP HEAD
patch(url, **kwargs) HTTP PATCH
execute_request(method, url, **kwargs) Generic request with full options
typed_request(Request) Strongly-typed request
stream_to_file(method, url, path) Stream response body to disk
clear_client_pool() Close idle connections (static)

Response

Property / Method Description
status_code HTTP status code (int)
headers Case-insensitive response headers
content Raw bytes body
text Decoded text body
encoding Detected charset
url Final URL after redirects
cookies Requests cookie jar
history Redirect response history
request The originating PreparedRequest
raw File-like buffered raw response
used_protocol Protocol used (e.g. HTTP/2.0)
ok True if status_code < 400
reason HTTP reason phrase
json() Parse body as JSON
raise_for_status() Raise tls_client.exceptions.HTTPError on 4xx/5xx
iter_content() / iter_lines() Iterate over buffered response data

🔗 Credits

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

📄 License

MIT — see LICENSE.

🙏 Community

Join the Discord server for support and discussion.

Powered by
JetBrains logo.

Project links

Data verified by PyPI on Sep 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.16.0.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for komAAmok from gravatar.com komAAmok

Credits

Author: komAAmok

GitHub Statistics

Data verified by PyPI on Sep 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.6

Tags

tls tls-fingerprint http-client ja3 http2 http3 quic cffi akamai cloudflare anti-bot

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tls_client_python-1.16.0.tar.gz (38.7 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tls_client_python-1.16.0-py3-none-win_amd64.whl (3.5 MB view details)

Uploaded Python 3Windows x86-64

tls_client_python-1.16.0-py3-none-win32.whl (3.1 MB view details)

Uploaded Python 3Windows x86

tls_client_python-1.16.0-py3-none-musllinux_1_1_x86_64.whl (4.8 MB view details)

Uploaded Python 3musllinux: musl 1.1+ x86-64

tls_client_python-1.16.0-py3-none-manylinux2014_x86_64.whl (4.8 MB view details)

Uploaded Python 3

tls_client_python-1.16.0-py3-none-manylinux2014_i686.whl (4.9 MB view details)

Uploaded Python 3

tls_client_python-1.16.0-py3-none-manylinux2014_armv7l.whl (4.6 MB view details)

Uploaded Python 3

tls_client_python-1.16.0-py3-none-manylinux2014_aarch64.whl (4.5 MB view details)

Uploaded Python 3

tls_client_python-1.16.0-py3-none-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

tls_client_python-1.16.0-py3-none-macosx_10_9_x86_64.whl (4.6 MB view details)

Uploaded Python 3macOS 10.9+ x86-64

File details

Details for the file tls_client_python-1.16.0.tar.gz.

File metadata

  • Download URL: tls_client_python-1.16.0.tar.gz
  • Upload date:
  • Size: 38.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tls_client_python-1.16.0.tar.gz
Algorithm Hash digest
SHA256 3c9a8f08614c033d8e724507d425f5a56872522c8b4688acd87f081f7619d6c4
MD5 4b6909ded0ef502982a03263dac11a19
BLAKE2b-256 a1273c85363f024d73b91a4d73e3f6196cf11dc59bda8bcf1036ebfef46b65dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0.tar.gz:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 61d67e4c72f89c496fd3d752765e60971c33b036fe081d96fb2c00b56845cccb
MD5 b9e2b673d8067f827cea27988fe68cea
BLAKE2b-256 483d95aa03047febcb3ba2eca667266330a93d2eb7d27369f45ce9b63bb967f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-win_amd64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-win32.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-win32.whl
Algorithm Hash digest
SHA256 8ab03b5e54fe0a5e035017d1216e44c9c8cd79d036064c7d26bb74703615b562
MD5 c871fb1d2bb70af611f6845a25386eba
BLAKE2b-256 67877353b179072c59e4eadc21236bdf1a60c25d1ec4e220d46d1c1400cab803

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-win32.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 e575d854e2b0e2bd83ff162cd6d9a10a196f724935a4d942627a09e5e951c09a
MD5 374c7bd4fad264c8028aaf0c565cd927
BLAKE2b-256 bb2bd2ee9bfc7a7ec304bf481f3e895630cb5cfd75c7b209ea8e6fe1f520b3ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-musllinux_1_1_x86_64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 709961b46cd5871f0bf2d947e194c6759ab3b9bf8772985f90d408df29682205
MD5 e7fd6e2226b73dbfb4ddec4594895873
BLAKE2b-256 7229aff8f57e36e860ba54b01b48a20a8014c2896a889b53987c6f4e8b533a72

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-manylinux2014_x86_64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-manylinux2014_i686.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-manylinux2014_i686.whl
Algorithm Hash digest
SHA256 bf6ef6d2fa918ef0cb5b8ef76965b4686a605e53139a04468770cdc3f9484f2b
MD5 2c35d2dc1554b3bf79d82ce5faad50ca
BLAKE2b-256 15fc82aec143ea9bb343539ef3152ef3ff759ee23652f28e7ffde0f1679693e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-manylinux2014_i686.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-manylinux2014_armv7l.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 c3796db0ca519940c99afe940858d6f3289bcd0d8f7ab955a73c95a8ccc68b9e
MD5 adcde24efb08f33a61fce52cc5e77308
BLAKE2b-256 377f9f074153db487f1e5fe5ab048d547b1a4dcd4d80d03ee15a9aec74ac615f

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-manylinux2014_armv7l.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c0eeb1ad1497170c221779941560f73027933835f2bcc877ed0fd3c40459c99f
MD5 1b8197fa4ef51d3bdc434a869274dd69
BLAKE2b-256 9ca1c03f300e3fc084b23040425a0c5761238538b5590d1dba2a71f671dfa289

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-manylinux2014_aarch64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b52cef8097bb2d3401326e2ac0d94b4371c8c6ec3c0b9bc68c9923c91e394fb9
MD5 2f81f9d7f640f7381e44c0b853179db6
BLAKE2b-256 89f88201daeada60be38423eaa375910571999f4e1206e7351ea0653cbe74bee

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-macosx_11_0_arm64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tls_client_python-1.16.0-py3-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for tls_client_python-1.16.0-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 7209d9fe1dfbb78f93392ef3db09c8553af00053834b746c7128eb757e0a8f1d
MD5 1373f223504f47be874f678f0a7983ac
BLAKE2b-256 2e864e4494a80866dd492040b5da68e4b91f33aaf2334ef68b6d709472b2d833

See more details on using hashes here.

Provenance

The following attestation bundles were made for tls_client_python-1.16.0-py3-none-macosx_10_9_x86_64.whl:

Publisher: build_workflow.yml on komAAmok/tls-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.16.0.4

14 files

1.16.0.3

14 files

1.16.0.2

14 files

1.16.0.1

14 files

This release

1.16.0 This release

10 files

1.15.1.1

10 files

1.15.1

10 files

1.15.0.4

10 files

1.15.0.3

10 files

1.15.0.2

11 files

1.15.0.1

2 files

1.15.0

2 files

1.14.1

2 files

1.14.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page