{"id":4805,"library":"tls-client","title":"TLS Client","description":"Python-TLS-Client is an advanced HTTP client library (version 1.0.1) designed to mimic browser-like TLS fingerprints and behavior, helping to bypass bot protection mechanisms. It offers a similar syntax to the popular `requests` library. The library maintains an active development pace, with frequent updates incorporating new features and shared library improvements.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/FlorianREGAZ/Python-Tls-Client","tags":["http client","tls fingerprinting","web scraping","networking","bot evasion"],"install":[{"cmd":"pip install tls-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The library is inspired by and aims to be API-compatible with the `requests` library.","package":"requests","optional":false}],"imports":[{"note":"The primary class is `Session` and is accessed directly from the `tls_client` module, not from a subcommand or differently named class.","wrong":"from tls_client import TLSClientSession","symbol":"Session","correct":"import tls_client\nsession = tls_client.Session()"}],"quickstart":{"code":"import tls_client\nimport os\n\n# Initialize a TLS client session mimicking Chrome 120\nsession = tls_client.Session(\n    client_identifier=\"chrome120\", \n    random_tls_extension_order=True,\n    proxy=os.environ.get('TLS_PROXY', '') # Optional: load proxy from environment variable\n)\n\ntry:\n    # Make a GET request with browser-like headers\n    response = session.get(\n        \"https://www.example.com/\",\n        headers={\n            \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\",\n            \"Accept\": \"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7\",\n            \"Accept-Language\": \"en-US,en;q=0.9\",\n            \"Accept-Encoding\": \"gzip, deflate, br\"\n        },\n        timeout_seconds=30\n    )\n\n    print(f\"Status Code: {response.status_code}\")\n    print(f\"Response Body (first 200 chars): {response.text[:200]}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    session.close() # Crucial for releasing resources and preventing memory leaks","lang":"python","description":"This quickstart demonstrates how to create a TLS client session, configure it to mimic a specific browser (Chrome 120), make a GET request to a URL with appropriate headers, and ensure the session is properly closed to avoid resource leaks."},"warnings":[{"fix":"Always call `session.close()` when the session is no longer needed, or use the `Session` object within a `with` statement if context manager support is available in a future version.","message":"Failing to explicitly call `session.close()` can lead to significant memory leaks, especially in long-running applications or when making many requests. Version 1.0.0 introduced the `close` function to address this.","severity":"gotcha","affected_versions":"<=1.0.1"},{"fix":"Include a `User-Agent` header in your request dictionary, e.g., `headers={'User-Agent': '...'}`.","message":"While `client_identifier` helps mimic TLS fingerprints, it may not automatically set the `User-Agent` header. For full browser-like behavior and to bypass some bot detection, manually specify a `User-Agent` header in your requests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully follow the documentation for generating and implementing certificate pins. Ensure you pin multiple certificates (current, backup, and CA) to prevent breakage during certificate rotation.","message":"Certificate pinning, added in version 1.0.1, requires pre-generating pins using a separate GoLang tool (`hpkp-pins`). Misconfiguration or failure to provide valid pins can lead to connection failures, as it rigorously validates server certificates.","severity":"gotcha","affected_versions":">=1.0.1"},{"fix":"Upgrade to the latest version of `tls-client` (1.0.0 or newer) to benefit from fixes in cookie management and other areas.","message":"Older versions (pre-1.0.0) of `tls-client` had known bugs related to cookie handling (e.g., duplicate cookies, issues with auto-redirects). Using outdated versions might lead to unexpected behavior in stateful interactions. [cite: GitHub releases]","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure your operating system and Python environment are up-to-date, with OpenSSL versions that support TLS 1.2+ (ideally 1.1.1 or newer for TLS 1.3).","message":"Connections might fail if the underlying system's OpenSSL library or Python environment does not support modern TLS protocols (like TLS 1.2 or 1.3), as many servers deprecate older, insecure versions like TLS 1.0/1.1.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If experiencing unusual memory usage or connection issues, try initializing the session with `force_http1=True`: `tls_client.Session(..., force_http1=True)`.","message":"Some users have reported memory or connection issues that could be mitigated by forcing HTTP/1.1 instead of HTTP/2. This may indicate specific server or environmental compatibility challenges with the underlying GoLang library's HTTP/2 implementation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}