httpmorph

A Python HTTP client focused on mimicking browser fingerprints.

⚠️ Work in Progress - This library is in early development. Features and API may change.

Features

Requests-compatible API - Drop-in replacement for most Python requests use cases
High Performance - Native C implementation with BoringSSL for HTTP/HTTPS
HTTP/2 Support - Full HTTP/2 with ALPN negotiation via nghttp2 (httpx-like API)
Chrome 127-143 Fingerprints - Perfect JA4 fingerprint matching
Browser Fingerprinting - Realistic Chrome browser profiles (127-143)
TLS Fingerprinting - JA3N/JA4/JA4_R fingerprint generation with post-quantum crypto
HTTP/2 Fingerprinting - Perfect Akamai HTTP/2 fingerprint matching
Connection Pooling - Automatic connection reuse for better performance
Session Management - Persistent cookies and headers across requests

Installation

pip install httpmorph

Platform Support

httpmorph provides pre-built wheels for maximum compatibility:

Platform	Architectures	Python Versions
Linux	x86_64, aarch64 (ARM64)	3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
macOS	Intel (x86_64), Apple Silicon (arm64)*	3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Windows	x64 (AMD64)	3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14

*macOS wheels are universal2 binaries supporting both Intel and Apple Silicon

Total Coverage: 28 pre-built wheels serving 99%+ of Python users

Requirements

Python 3.8 or later
No compilation required - batteries included!

Quick Start

import httpmorph

# Simple GET request
response = httpmorph.get('https://icanhazip.com')
print(response.status_code)
print(response.text)

# POST with JSON
response = httpmorph.post(
    'https://httpbin.org/post',
    json={'key': 'value'}
)

# Using sessions
session = httpmorph.Session(browser='chrome')
response = session.get('https://example.com')

# HTTP/2 support (httpx-like API)
client = httpmorph.Client(http2=True)
response = client.get('https://www.google.com')
print(response.http_version)  # '2.0'

Browser Profiles

Mimic real browser behavior with pre-configured profiles:

# Use Chrome fingerprint (defaults to Chrome 143)
response = httpmorph.get('https://example.com', browser='chrome')

# Use specific Chrome version (127-143 supported)
session = httpmorph.Session(browser='chrome143')
response = session.get('https://example.com')

# Available browsers: chrome, chrome127-chrome143

OS-Specific User Agents

httpmorph supports different operating system user agents to simulate requests from various platforms:

import httpmorph

# macOS (default)
session = httpmorph.Session(browser='chrome', os='macos')
# User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...

# Windows
session = httpmorph.Session(browser='chrome', os='windows')
# User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...

# Linux
session = httpmorph.Session(browser='chrome', os='linux')
# User-Agent: Mozilla/5.0 (X11; Linux x86_64) ...

Supported OS values:

macos - macOS / Mac OS X (default)
windows - Windows 10/11
linux - Linux distributions

The OS parameter only affects the User-Agent string, while all other fingerprinting characteristics (TLS, HTTP/2, JA3/JA4) remain consistent to match the specified browser profile.

Chrome Fingerprint Matching

httpmorph accurately mimics Chrome 127-143 TLS and HTTP/2 fingerprints with:

JA4 ✅ Perfect match (t13d1516h2_8daaf6152771_d8a2da3f94cd)
JA4_R ✅ Perfect match
JA3N ✅ Perfect match (normalized JA3: dcefaf3f0e71d260d19dc1d0749c9278)
HTTP/2 Akamai ✅ Perfect match (1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p)
User-Agent: Version-specific Chrome user agents
TLS 1.3 with correct cipher suites and extensions
HTTP/2 with Chrome-specific SETTINGS frame and pseudo-header order
Post-quantum cryptography (X25519MLKEM768)
Certificate compression (Brotli)

Verify your fingerprint:

import httpmorph

# Make a request to fingerprint checker
response = httpmorph.get('https://tls.peet.ws/api/all', browser='chrome143')
data = response.json()
print(f"JA4: {data['tls']['ja4']}")

# Expected: t13d1516h2_8daaf6152771_d8a2da3f94cd ✅

All Chrome 127-143 profiles produce exact JA4 matches with real Chrome browsers.

Advanced Usage

HTTP/2 Support

httpmorph supports HTTP/2 with an httpx-like API:

# Both Client and Session default to HTTP/2 (http2=True) like Chrome
client = httpmorph.Client()
response = client.get('https://www.google.com')
print(response.http_version)  # '2.0'

session = httpmorph.Session(browser='chrome')
response = session.get('https://www.google.com')
print(response.http_version)  # '2.0'

# Per-request HTTP/2 override (disable for specific request)
client = httpmorph.Client()  # Defaults to HTTP/2
response = client.get('https://example.com', http2=False)  # Disable for this request

Custom Headers

headers = {
    'User-Agent': 'MyApp/1.0',
    'Authorization': 'Bearer token123'
}
response = httpmorph.get('https://api.example.com', headers=headers)

File Uploads

files = {'file': ('report.pdf', open('report.pdf', 'rb'))}
response = httpmorph.post('https://httpbin.org/post', files=files)

Timeout Control

# Single timeout value
response = httpmorph.get('https://example.com', timeout=5)

# Separate connect and read timeouts
response = httpmorph.get('https://example.com', timeout=(3, 10))

SSL Verification

# Disable SSL verification (not recommended for production)
response = httpmorph.get('https://example.com', verify_ssl=False)

Authentication

# Basic authentication
response = httpmorph.get(
    'https://api.example.com',
    auth=('username', 'password')
)

Redirects

# Follow redirects (default behavior)
response = httpmorph.get('https://example.com/redirect')

# Don't follow redirects
response = httpmorph.get(
    'https://example.com/redirect',
    allow_redirects=False
)

# Check redirect history
print(len(response.history))  # Number of redirects

Sessions with Cookies

session = httpmorph.Session()

# Cookies persist across requests
session.get('https://example.com/login')
session.post('https://example.com/form', data={'key': 'value'})

# Access cookies
print(session.cookies)

API Compatibility

httpmorph aims for high compatibility with Python's requests library:

Feature	Status
GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS	Supported
JSON request/response	Supported
Form data & file uploads	Supported
Custom headers	Supported
Authentication	Supported
Cookies & sessions	Supported
Redirects with history	Supported
Timeout control	Supported
SSL verification	Supported
Streaming responses	Supported
Exception hierarchy	Supported

Response Object

response = httpmorph.get('https://httpbin.org/get')

# Status and headers
print(response.status_code)      # 200
print(response.ok)                # True
print(response.reason)            # 'OK'
print(response.headers)           # {'Content-Type': 'application/json', ...}

# Response body
print(response.text)              # Response as string
print(response.body)              # Response as bytes
print(response.json())            # Parse JSON response

# Request info
print(response.url)               # Final URL after redirects
print(response.history)           # List of redirect responses

# Timing
print(response.elapsed)           # Response time
print(response.total_time_us)     # Total time in microseconds

# TLS info
print(response.tls_version)       # TLS version used
print(response.tls_cipher)        # Cipher suite
print(response.ja3_fingerprint)   # JA3 fingerprint

Exception Handling

import httpmorph

try:
    response = httpmorph.get('https://example.com', timeout=5)
    response.raise_for_status()  # Raise exception for 4xx/5xx
except httpmorph.Timeout:
    print("Request timed out")
except httpmorph.ConnectionError:
    print("Failed to connect")
except httpmorph.HTTPError as e:
    print(f"HTTP error: {e.response.status_code}")
except httpmorph.RequestException as e:
    print(f"Request failed: {e}")

Platform Support

Platform	Status
Windows	✅ Fully supported
macOS (Intel & Apple Silicon)	✅ Fully supported
Linux (x86_64, ARM64)	✅ Fully supported

All platforms use BoringSSL (Google's fork of OpenSSL) for consistent TLS behavior and advanced fingerprinting capabilities.

Building from Source

httpmorph uses BoringSSL (built from source) on all platforms for consistent TLS fingerprinting.

Prerequisites

Windows:

# Install build tools
choco install cmake golang nasm visualstudio2022buildtools -y

# Or install manually:
# - Visual Studio 2019+ (with C++ tools)
# - CMake 3.15+
# - Go 1.18+
# - NASM (for BoringSSL assembly optimizations)

macOS:

# Install dependencies
brew install cmake ninja libnghttp2

Linux:

# Ubuntu/Debian
sudo apt-get install cmake ninja-build libssl-dev pkg-config autoconf automake libtool

# Fedora/RHEL
sudo dnf install cmake ninja-build openssl-devel pkg-config autoconf automake libtool

Build Steps

# 1. Clone the repository
git clone https://github.com/arman-bd/httpmorph.git
cd httpmorph

# 2. Build vendor dependencies (BoringSSL, nghttp2, zlib)
./scripts/setup_vendors.sh  # On Windows: bash scripts/setup_vendors.sh

# 3. Build Python extensions
python setup.py build_ext --inplace

# 4. Install in development mode
pip install -e ".[dev]"

Note: The first build takes 5-10 minutes as it compiles BoringSSL from source. Subsequent builds are much faster (~30 seconds) as the vendor libraries are cached.

Development

# Clone and setup (includes building BoringSSL)
git clone https://github.com/arman-bd/httpmorph.git
cd httpmorph
./scripts/setup_vendors.sh

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=httpmorph --cov-report=html

# Run specific test markers
pytest tests/ -m "not slow"           # Skip slow tests
pytest tests/ -m "not proxy"          # Skip proxy tests (default in CI)
pytest tests/ -m proxy                # Only proxy tests
pytest tests/ -m integration          # Only integration tests
pytest tests/ -m fingerprint          # Only fingerprinting tests

Architecture

httpmorph combines the best of both worlds:

C Core: Low-level HTTP/TLS implementation for maximum performance
Python Wrapper: Clean, Pythonic API with requests compatibility
BoringSSL: Google's fork of OpenSSL, optimized and battle-tested
nghttp2: Standard-compliant HTTP/2 implementation

The library uses Cython to bridge Python and C, providing near-native performance with the ease of Python.

Contributing

Contributions are welcome! Areas where help is especially appreciated:

Windows compatibility
Additional browser profiles
Performance optimizations
Documentation improvements
Bug reports and fixes

Please open an issue or pull request on GitHub.

Testing

httpmorph has a comprehensive test suite with 350+ tests covering:

All HTTP methods and parameters
Chrome 127-143 fingerprint validation (JA4, JA4_R)
TLS 1.2/1.3 with post-quantum cryptography
Certificate compression (Brotli, Zlib)
Redirect handling and history
Cookie and session management
Authentication and SSL
Error handling and timeouts
Unicode and encoding edge cases
Thread safety and memory management
Real-world integration tests

Run the test suite:

pytest tests/ -v

Acknowledgments

Built on BoringSSL (Google) with post-quantum cryptography support
HTTP/2 support via nghttp2
Inspired by Python's requests and httpx libraries
Chrome 127-143 fingerprint matching with perfect JA4, JA3N, and HTTP/2 Akamai fingerprints
Certificate compression (Brotli) for Cloudflare-protected sites

FAQ

Q: Why another HTTP client? A: httpmorph combines the performance of native C with browser fingerprinting capabilities, making it ideal for applications that need both speed and realistic browser behavior.

Q: How accurate are the Chrome fingerprints? A: httpmorph achieves perfect JA4 matches for Chrome 127-143. Test your fingerprint at https://tls.peet.ws/api/all

Q: Is it production-ready? A: No, httpmorph is still in active development and not yet recommended for production use.

Q: Can I use this as a drop-in replacement for requests? A: For most common use cases, yes! We've implemented the most widely-used requests API. Some advanced features may have slight differences.

Q: Does it work with Cloudflare-protected sites? A: Yes! httpmorph supports certificate compression (Brotli) which is required for many Cloudflare-protected sites. We successfully tested with icanhazip.com and postman-echo.com.

Q: How do I report a bug? A: Please open an issue on GitHub with a minimal reproduction example and your environment details (OS, Python version, httpmorph version).

Support

GitHub Issues: Report bugs and feature requests
Documentation: Full API documentation
PyPI: httpmorph on PyPI

License

MIT License - See LICENSE file for details.

Legal Disclaimer

FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY

This software is provided for educational, research, authorized security testing, and development purposes only.

No Affiliation: This software is not affiliated with, endorsed by, or connected to Google, Chrome, or any browser vendors. All trademarks are property of their respective owners.

User Responsibility: You are solely responsible for your use of this software and any consequences. You must:

Obtain proper authorization before testing systems you don't own
Comply with all applicable laws, regulations, and terms of service
Respect robots.txt and website usage policies
NOT use this for illegal, unauthorized, or malicious activities

Prohibited Uses: Do not use this software for bypassing security measures without authorization, violating terms of service, unauthorized access, unauthorized web scraping, circumventing rate limits, fraud, harassment, or any illegal activities.

Disclaimer: The authors disclaim all liability for any damages arising from use or misuse of this software. This software is provided "AS IS" without warranties of any kind. Use at your own risk.

Agreement: By using this software, you agree to these terms. If you disagree, do not use this software.

Use this tool ethically and legally. You assume all risks and responsibilities.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
benchmarks		benchmarks
bin		bin
docker		docker
docs		docs
examples		examples
hooks		hooks
include		include
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
.readthedocs.yaml		.readthedocs.yaml
.ruff.toml		.ruff.toml
.ruffignore		.ruffignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
coverage.xml		coverage.xml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
setup.py		setup.py

License

arman-bd/httpmorph

Folders and files

Latest commit

History

Repository files navigation

httpmorph

Features

Installation

Platform Support

Requirements

Quick Start

Browser Profiles

OS-Specific User Agents

Chrome Fingerprint Matching

Advanced Usage

HTTP/2 Support

Custom Headers

File Uploads

Timeout Control

SSL Verification

Authentication

Redirects

Sessions with Cookies

API Compatibility

Response Object

Exception Handling

Platform Support

Building from Source

Prerequisites

Build Steps

Development

Architecture

Contributing

Testing

Acknowledgments

FAQ

Support

License

Legal Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Languages

Packages