Skip to main content

Python Proxy Headers

Documentation Status PyPI version

Extensions for Python HTTP libraries to support sending and receiving custom proxy headers during HTTPS CONNECT tunneling.

The Problem

When making HTTPS requests through a proxy, the connection is established via a CONNECT tunnel. During this process:

  1. Sending headers to the proxy - Most Python HTTP libraries don't provide an easy way to send custom headers (like X-ProxyMesh-Country) to the proxy server during the CONNECT handshake.

  2. Receiving headers from the proxy - The proxy's response headers from the CONNECT request are typically discarded, making it impossible to read custom headers (like X-ProxyMesh-IP) that the proxy sends back.

This library solves both problems for popular Python HTTP libraries.

Supported Libraries

Library Module Use Case
urllib3 urllib3_proxy_manager Low-level HTTP client
requests requests_adapter Simple HTTP requests
aiohttp aiohttp_proxy Async HTTP client
httpx httpx_proxy Modern HTTP client
pycurl pycurl_proxy libcurl bindings
cloudscraper cloudscraper_proxy Cloudflare bypass
autoscraper autoscraper_proxy Automatic web scraping

Installation

pip install python-proxy-headers

Then install the HTTP library you want to use (e.g., pip install requests).

Note: This package has no dependencies by default - install only what you need.

Quick Start

requests

from python_proxy_headers.requests_adapter import ProxySession

with ProxySession(proxy_headers={'X-ProxyMesh-Country': 'US'}) as session:
    session.proxies = {'https': 'http://user:pass@proxy.example.com:8080'}
    response = session.get('https://httpbin.org/ip')
    
    # Proxy headers are merged into response.headers
    print(response.headers.get('X-ProxyMesh-IP'))

httpx

from python_proxy_headers.httpx_proxy import get

response = get(
    'https://httpbin.org/ip',
    proxy='http://user:pass@proxy.example.com:8080'
)

# Proxy CONNECT response headers are merged into response.headers
print(response.headers.get('X-ProxyMesh-IP'))

aiohttp

import asyncio
from python_proxy_headers.aiohttp_proxy import ProxyClientSession

async def main():
    async with ProxyClientSession() as session:
        async with session.get(
            'https://httpbin.org/ip',
            proxy='http://user:pass@proxy.example.com:8080'
        ) as response:
            # Proxy headers merged into response.headers
            print(response.headers.get('X-ProxyMesh-IP'))

asyncio.run(main())

pycurl (low-level)

import pycurl
from python_proxy_headers.pycurl_proxy import set_proxy_headers, HeaderCapture

c = pycurl.Curl()
c.setopt(pycurl.URL, 'https://httpbin.org/ip')
c.setopt(pycurl.PROXY, 'http://proxy.example.com:8080')

# Add these two lines to any existing pycurl code
set_proxy_headers(c, {'X-ProxyMesh-Country': 'US'})
capture = HeaderCapture(c)

c.perform()

print(capture.proxy_headers)  # Headers from proxy CONNECT response
c.close()

cloudscraper

from python_proxy_headers.cloudscraper_proxy import create_scraper

# Drop-in replacement for cloudscraper.create_scraper()
scraper = create_scraper(proxy_headers={'X-ProxyMesh-Country': 'US'})
scraper.proxies = {'https': 'http://proxy.example.com:8080'}

response = scraper.get('https://example.com')
# All CloudScraper features (Cloudflare bypass) preserved

Testing

A test harness is included to verify proxy header functionality:

# Set your proxy
export PROXY_URL='http://user:pass@proxy.example.com:8080'

# Test all modules
python test_proxy_headers.py

# Test specific modules
python test_proxy_headers.py requests httpx

# Verbose output (show header values)
python test_proxy_headers.py -v

Documentation

For detailed documentation, API reference, and more examples:

About

Created by ProxyMesh to help our customers use custom headers to control proxy behavior. Works with any proxy that supports custom headers.

License

MIT License

Metadata

Release files for python-proxy-headers 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-proxy-headers 0.2.4
File Size Uploaded Provenance Actions
python_proxy_headers-0.2.4.tar.gz 21.0 kB With provenance Details for python_proxy_headers-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-proxy-headers 0.2.4
File Interpreter ABI Platform Actions
python_proxy_headers-0.2.4-py3-none-any.whl Python 3 none any Details for python_proxy_headers-0.2.4-py3-none-any.whl

Total release size: 44.0 kB

Release files / python_proxy_headers-0.2.4.tar.gz

Download URL python_proxy_headers-0.2.4.tar.gz
Size 21.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ce8b81f4ded1aecd58a268a1ab7172bd4d6a1213419fe7449d3441cb3b5963cc
BLAKE2b-256 checksum
How to use checksums
4ee9c2fe84c1f248229acdcf9e3bb2c85e2053581bd2a7b6fc164f748e9e15b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / python_proxy_headers-0.2.4-py3-none-any.whl

Download URL python_proxy_headers-0.2.4-py3-none-any.whl
Size 23.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bef0821422f369492a2f8c82da0c044c5c69a540737b03935073b164323a2daf
BLAKE2b-256 checksum
How to use checksums
4d3ae53ba2cbc1a3faa7ecec682f02f84bcafbba4ca25e693f85f425df4f9493
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for python-proxy-headers 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python_proxy_headers-0.2.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page