Install & Compatibility
Where this runs
tested against v1.2.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.784s · 20.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.690s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TLSClient
✓ from tls_requests import TLSClient
✗ from tls_requests import TLSSession
Before v1.1.0, the main class was TLSSession; renamed for consistency.
TLSResponse
✓ from tls_requests import TLSResponse
Initialize a TLSClient and make a GET request with a custom User-Agent to mimic a browser.
from tls_requests import TLSClient
client = TLSClient()
response = client.get('https://httpbin.org/get', headers={'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'})
print(response.text)
Debug
Known issues
deprecatedThe module name 'wrapper_tls_requests' is deprecated; use 'tls_requests'.fixRun `pip uninstall wrapper-tls-requests && pip install wrapper-tls-requests` and update imports to `from tls_requests import ...`.
affects: v1.2.0+
gotchaTLSClient is not thread-safe; sharing a client across threads may cause race conditions.fixCreate a new TLSClient instance per thread or use threading.Lock.
affects: all
breakingIn v1.2.0, the default TLS fingerprint changed, breaking responses that depend on the old fingerprint.fixSpecify the desired fingerprint explicitly: TLSClient(tls_client_id='chrome_120') or use the 'TLSClient.from_session' method to replicate a known session.
affects: v1.2.0 and later
gotchaHTTP proxy support requires explicit configuration; environment variables (HTTP_PROXY, HTTPS_PROXY) are not automatically honored.fixPass proxies dict to client.get(proxies={'http': 'http://proxy:8080', 'https': 'http://proxy:8080'}) or set client.proxies. affects: all
Errors
Common errors & fixes
ImportError: cannot import name 'TLSClient' from 'tls_requests'
The old import path used 'wrapper_tls_requests' or the class was named 'TLSSession' in older versions.
fixInstall latest version and use `from tls_requests import TLSClient`. If using an older version, check documentation for correct class.
tls_requests.exceptions.TLSClientInitializationError: Failed to initialize TLS client. Ensure tls-client binary is available.
The underlying tls-client binary is missing or corrupted.
fixRun `pip install wrapper-tls-requests` again to reinstall the binary, or manually download from https://github.com/thewebscraping/tls-client-binary.
AttributeError: 'TLSClient' object has no attribute 'session'
Incorrect usage: the client does not have a session attribute; use the client directly.
fixReplace `client.session.get(...)` with `client.get(...)`.
Upgrade
Version history
1.2.5latest on PyPI · released Feb 23, 2026
Audit
Dependencies
No dependency data recorded yet.