tlsmask

Python HTTP requests with a real browser's TLS and HTTP/2 fingerprint.

tlsmask makes HTTP requests from Python that look like they come from Chrome, Firefox or Safari. Not just the headers: the TLS handshake and the HTTP/2 settings match the browser too. It runs bogdanfinn's tls-client, a Go library, and ships its latest official build inside the package.

It is also a drop-in replacement for the tls-client package, which hasn't had a release since February 2024.

import tlsmask

with tlsmask.Session("chrome_150") as session:
    r = session.get("https://tls.peet.ws/api/all")
    print(r.status_code, r.protocol)  # 200 HTTP/2.0
    print(r.json()["tls"]["ja4"])  # Chrome's fingerprint, not Python's

Why

Every HTTPS connection starts with a TLS "ClientHello": a list of the ciphers, extensions and curves the client supports, in a particular order. Each browser sends its own recognisable version (often summarised as a JA3 or JA4 fingerprint), and so does Python. A server can tell them apart before it reads a single header, which is why requests with a Chrome User-Agent still doesn't look like Chrome.

bogdanfinn's tls-client reproduces real browsers' handshakes and HTTP/2 behaviour. The tls-client package made it usable from Python, but it stopped at version 1.0.1. It still bundles tls-client v1.7.2, so its newest browser is Chrome 120, and a number of its bugs were never fixed.

tlsmask carries on from there: the current library, the same API, those bugs fixed, and a weekly check for new tls-client releases.

tlsmask compared with tls-client

Installation

pip install tlsmask

Prebuilt wheels are available for:

• Windows, 64-bit and 32-bit
• macOS 13 or newer, Apple Silicon and Intel
• Linux x86-64, ARM64 and ARMv7 (glibc 2.17 or newer)

Each wheel already contains the tls-client library for its platform, so nothing is downloaded when your code runs. tlsmask needs Python 3.9 or newer and has no other dependencies.

Usage

import tlsmask

session = tlsmask.Session("chrome_150")
session.headers.update(
    {
        "User-Agent": (
            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
            "(KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36"
        ),
        "Accept-Language": "en-US,en;q=0.9",
    }
)

r = session.get("https://example.com", params={"q": "tls"})
print(r.status_code, r.headers["content-type"])

r = session.post("https://httpbin.org/post", json={"hello": "world"})
print(r.json())

session.close()

With asyncio:

import asyncio

import tlsmask


async def main():
    async with tlsmask.AsyncSession("firefox_148") as session:
        pages = await asyncio.gather(
            *(session.get(f"https://example.com/?page={i}") for i in range(10))
        )
        print([page.status_code for page in pages])


asyncio.run(main())

The guide covers the rest: header order, cookies, proxies, redirects, timeouts, errors, threads, custom TLS fingerprints and how to check your install.

Switching from tls-client

- import tls_client
+ import tlsmask as tls_client

For most code that's the only change. The constructor arguments, the request methods, response.json() and the session.cookies helpers work the same way. A few things behave differently on purpose, mostly because the old behaviour was a bug:

The old misspelled TLSClientExeption still works. If your code imports tls_client.settings.ClientIdentifiers, use tlsmask.ClientIdentifiers instead. response.headers is case-insensitive now, so use dict(response.headers) where you need a plain dict (for json.dumps, say).

Choosing a profile

For most uses, pick a current browser, such as the default (tlsmask.DEFAULT_PROFILE), firefox_148 or safari_ios_26_0. Send a User-Agent that matches the profile, because a Firefox User-Agent over a Chrome handshake stands out on its own. The _PSK variants resume TLS sessions the way a returning visitor's browser does.

tlsmask.PROFILES holds every name, and editors autocomplete them through the tlsmask.ClientIdentifier type.

Where the library comes from

The native part of tlsmask is bogdanfinn's own release file, byte for byte. It isn't rebuilt or modified.

1. When a wheel is built, the file is downloaded from tls-client's GitHub releases. The build refuses it unless its SHA-256 matches both the hash pinned in tlsmask/_pins.py and the digest GitHub publishes for the release.
2. The first time your program makes a request, tlsmask hashes the file again and won't load it if it doesn't match.
3. Releases are published to PyPI from GitHub Actions with trusted publishing and signed attestations, and every GitHub release includes a SHA256SUMS file.

To check your own installation:

$ python -m tlsmask
tlsmask     1.16.0
tls-client  1.16.0 (github.com/bogdanfinn/tls-client)
platform    win32/AMD64 (64-bit Python) -> windows-amd64
library     OK: ...\tlsmask\bin\tls-client-windows-64-1.16.0.dll (sha256 53dca636..., as pinned)

Staying up to date

Every Monday a scheduled job looks for a new tls-client release. When there is one, it downloads and verifies every file, reads the new list of profiles, compares the library's API with the previous version, and runs the full test suite on Windows, macOS and Linux, on both Intel and ARM machines.

If nothing important changed and the release is at least a week old, a new tlsmask version is published automatically. Anything unusual, like a removed profile or a changed API, waits for a person to look at it first.

FAQ

Is this an official bogdanfinn project? No. tlsmask is an independent project and isn't affiliated with or endorsed by Bogdan Finn. It bundles his library unmodified. Please report tlsmask problems here rather than to him.

Does it work on Alpine Linux? Not at the moment. tls-client's Alpine (musl) build can't be loaded into Python, so there is no Alpine wheel. In Docker, use a glibc-based image such as python:3.12-slim instead.

My platform has no wheel. Get a build of tls-client for it (from its releases, or build it yourself) and point tlsmask at the file with the TLSMASK_LIBRARY_PATH environment variable. On such a platform pip install tlsmask installs from the source distribution, which has no library of its own.

Does it work with multiprocessing? Yes. The library is only loaded when the first request is made, so child processes are fine as long as the parent hadn't made a request before it forked. If in doubt, use the spawn start method (the default on Windows and macOS).

Why aren't redirects followed by default? tls-client didn't follow them by default, so existing code keeps working. Pass allow_redirects=True.

What is it for? Making requests that look like a real browser: testing your own site's bot protection, research, or talking to APIs that turn away non-browser clients. Please respect the terms of the sites you use it with.

Contributing

Bug reports and pull requests are welcome. To set up a development copy:

git clone https://github.com/Ubaidullah71/tlsmask && cd tlsmask
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python scripts/fetch_binaries.py  # downloads and verifies this machine's library into tlsmask/bin/
pytest                            # unit tests, plus tests against the real library and a local server
pytest -m live                    # fingerprint checks against a public echo service

tlsmask/_pins.py, tlsmask/profiles.py, tlsmask/_version.py and the tables in this README are generated by scripts/render.py, so please don't edit them by hand.

Credits

• bogdanfinn/tls-client does the real work. This product includes software developed by Bogdan Finn, distributed under the BSD 4-Clause license (see LICENSE-tls-client).
• FlorianREGAZ/Python-Tls-Client designed the Python API that tlsmask keeps compatible.

License

tlsmask's own code is under the MIT license. The bundled tls-client library is under the BSD 4-Clause license (LICENSE-tls-client).