primp

When using impersonation, primp modifies the following layers of the network request:

• TLS fingerprint: cipher suites, signature algorithms, named groups, extension order.
• HTTP/2 fingerprint: SETTINGS order, pseudo-header order, header priority, header order, initial window sizes.
• Headers: User-Agent, sec-ch-ua, Accept, Accept-Language, Accept-Encoding, sec-fetch-*, etc.
• Compression: Support for gzip, brotli, and zstd per browser profile.

If you provide a list to dns_resolver, primp will attempt to use the resolvers in the order they are listed. The first resolver that succeeds will be used. This is useful for attempting secure protocols like DoH or DoT first, then falling back to the system resolver or plain DNS if they fail.

# Try DoH first, fall back to system
client = primp.Client(dns_resolver=["doh://cloudflare-dns.com/dns-query", "system"])

# Try DoH first, fall back to plain DNS
client = primp.Client(dns_resolver=["doh://cloudflare-dns.com/dns-query", "1.1.1.1"])

To avoid detection, you can configure the client to mimic specific browser and OS fingerprints using the impersonate and impersonate_os arguments in the Client constructor.

Supported Browser Profiles (impersonate):

• Chrome: chrome_144, chrome_145, chrome_146, chrome
• Safari: safari_18.5, safari_26, safari_26.3, safari
• Edge: edge_144, edge_145, edge_146, edge
• Firefox: firefox_140, firefox_146, firefox_147, firefox_148, firefox
• Opera: opera_126, opera_127, opera_128, opera_129, opera
• Random: random

Supported OS Profiles (impersonate_os):

• android, ios, linux, macos, windows, random

To use primp in your Rust project, add it to your Cargo.toml dependencies file.

[dependencies]
primp = "1"

You can create an HTTP client that impersonates a specific web browser using Client::builder() and the .impersonate() method. This allows your requests to mimic the TLS and HTTP/2 fingerprints of real browsers.

use primp::{Client, Impersonate};

#[tokio::main]
async fn main() -> Result<(), primp::Error> {
    let client = Client::builder()
        .impersonate(Impersonate::ChromeV146)
        .build()?;
    let resp = client.get("https://tls.peet.ws/api/all").send().await?;
    println!("Body: {}", resp.text().await?);
    Ok(())
}

When using streaming responses, always use a context manager to prevent resource leaks. If you do not use a context manager, you must manually call .close() (sync) or .aclose() (async) on the response object.

Recommended Pattern:

with primp.get(url, stream=True) as resp:
    for chunk in resp.iter_bytes(65536):
        process(chunk)

Manual Pattern (Avoid if possible):

resp = primp.get(url, stream=True)
try:
    for chunk in resp.iter_bytes():
        process(chunk)
finally:
    resp.close()

# Good
with primp.get(url, stream=True) as resp:
    for chunk in resp.iter_bytes(65536):  # 64KB chunks
        process(chunk)

# Avoid — remember to call resp.close()
resp = primp.get(url, stream=True)
for chunk in resp.iter_bytes():
    process(chunk)
resp.close()

If you need to build primp from the source repository, follow these steps using maturin:

1. Clone the repository and navigate to the Python crate directory.
2. Create and activate a virtual environment.
3. Install maturin and run maturin develop -r to build and install the package in development mode.

git clone https://github.com/deedy5/primp.git && cd primp/crates/primp-python
python -m venv .venv && source .venv/bin/activate
pip install maturin && maturin develop -r

The AsyncClient is an asynchronous HTTP client designed to impersonate web browsers. It is best used within an async with context manager to ensure proper resource management. All request methods (GET, POST, etc.) return awaitable futures that must be awaited.

import asyncio
import primp

async def main():
    async with primp.AsyncClient(impersonate="chrome_146") as client:
        resp = await client.get("https://httpbin.org/get")
        print(resp.text)

asyncio.run(main())

You can benchmark primp against other Python HTTP clients including aiohttp, curl_cffi, httpx, pycurl, and requests. Note that the server response used in this benchmark is gzipped.

To execute the benchmark, run the following command from the benchmark directory:

python run.py