PycURL Proxy Configuration

PycURL provides Python bindings for PycURL, the powerful and widely-used HTTP client library. When you need maximum performance and detailed timing information, PycURL gives you direct access to all of libcurl's capabilities.

PycURL has built-in proxy support through libcurl's CURLOPT_PROXY options, making it easy to route traffic through ProxyMesh rotating proxies with C-level performance.

Why Choose PycURL?

Maximum performance - C-level speed for HTTP operations
Detailed timing - DNS lookup, connect, TLS handshake times
Protocol support - HTTP, HTTPS, FTP, and more
Connection reuse - Efficient keep-alive and multiplexing
Full libcurl access - Every curl option available

Installation

PycURL requires libcurl and development headers:

# Ubuntu/Debian
sudo apt-get install libcurl4-openssl-dev python3-dev

# macOS
brew install curl

# Then install PycURL
pip install pycurl

Installation

Install PycURL using pip (requires libcurl):

pip install pycurl

PycURL has built-in proxy support through libcurl—no additional packages needed.

Basic Proxy Configuration

PycURL uses libcurl's CURLOPT_PROXY option to configure proxies:

import pycurl
from io import BytesIO

curl = pycurl.Curl()

# Set URL and proxy
curl.setopt(pycurl.URL, "https://api.ipify.org?format=json")
curl.setopt(pycurl.PROXY, "us-wa.proxymesh.com")
curl.setopt(pycurl.PROXYPORT, 31280)
curl.setopt(pycurl.PROXYUSERPWD, "username:password")

# Capture response
buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)

curl.perform()
print(buffer.getvalue().decode())

curl.close()

Detailed Timing Information

PycURL provides granular timing metrics:

import pycurl
from io import BytesIO

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://api.ipify.org?format=json")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
curl.setopt(pycurl.PROXYUSERPWD, "user:pass")

buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)
curl.perform()

print(f"DNS lookup: {curl.getinfo(pycurl.NAMELOOKUP_TIME):.3f}s")
print(f"Connect: {curl.getinfo(pycurl.CONNECT_TIME):.3f}s")
print(f"TLS handshake: {curl.getinfo(pycurl.APPCONNECT_TIME):.3f}s")
print(f"Total time: {curl.getinfo(pycurl.TOTAL_TIME):.3f}s")
print(f"Primary IP: {curl.getinfo(pycurl.PRIMARY_IP)}")

curl.close()

IP Authentication

import pycurl
from io import BytesIO

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://api.ipify.org")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
# No PROXYUSERPWD needed with IP whitelisting

buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)
curl.perform()
curl.close()

Custom Proxy Headers

Send custom headers to the proxy using CURLOPT_PROXYHEADER (requires libcurl 7.37.0+):

import pycurl
from io import BytesIO

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://api.ipify.org?format=json")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
curl.setopt(pycurl.PROXYUSERPWD, "user:pass")
curl.setopt(pycurl.PROXYHEADER, ["X-ProxyMesh-Country: US"])

buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)
curl.perform()

print(buffer.getvalue().decode())
curl.close()

For easier proxy header handling, use the python-proxy-headers extension:

pip install python-proxy-headers

from python_proxy_headers import pycurl_request

response = pycurl_request.get(
    "https://api.ipify.org?format=json",
    proxy="http://user:pass@PROXYHOST:PORT",
    proxy_headers={"X-ProxyMesh-Country": "US"}
)

print(response.body.decode())
print(f"Routed through: {response.headers.get('X-ProxyMesh-IP')}")

Common Use Cases

Concurrent Requests with CurlMulti

import pycurl
from io import BytesIO

def create_handle(url, proxy):
    curl = pycurl.Curl()
    buffer = BytesIO()
    
    curl.setopt(pycurl.URL, url)
    curl.setopt(pycurl.PROXY, proxy)
    curl.setopt(pycurl.WRITEDATA, buffer)
    curl.setopt(pycurl.TIMEOUT, 30)
    curl.buffer = buffer
    
    return curl

urls = [f"https://httpbin.org/anything/{i}" for i in range(10)]
proxy = "user:pass@PROXYHOST:PORT"

handles = [create_handle(url, proxy) for url in urls]

multi = pycurl.CurlMulti()
for handle in handles:
    multi.add_handle(handle)

# Perform all requests concurrently
num_handles = len(handles)
while num_handles:
    ret = multi.select(1.0)
    if ret == -1:
        continue
    while True:
        ret, num_handles = multi.perform()
        if ret != pycurl.E_CALL_MULTI_PERFORM:
            break

for handle in handles:
    print(f"Status: {handle.getinfo(pycurl.RESPONSE_CODE)}, Time: {handle.getinfo(pycurl.TOTAL_TIME):.3f}s")
    multi.remove_handle(handle)
    handle.close()

multi.close()

POST with JSON

import pycurl
import json
from io import BytesIO

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://httpbin.org/post")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
curl.setopt(pycurl.PROXYUSERPWD, "user:pass")

data = json.dumps({"key": "value"})
curl.setopt(pycurl.POSTFIELDS, data)
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/json"])

buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)
curl.perform()

print(buffer.getvalue().decode())
curl.close()

Download Large Files

import pycurl

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://example.com/large-file.zip")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
curl.setopt(pycurl.PROXYUSERPWD, "user:pass")

with open("download.zip", "wb") as f:
    curl.setopt(pycurl.WRITEDATA, f)
    curl.perform()

print(f"Downloaded in {curl.getinfo(pycurl.TOTAL_TIME):.2f}s")
print(f"Speed: {curl.getinfo(pycurl.SPEED_DOWNLOAD) / 1024 / 1024:.2f} MB/s")

curl.close()

Verbose Debug Output

import pycurl
from io import BytesIO

curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://api.ipify.org")
curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
curl.setopt(pycurl.PROXYUSERPWD, "user:pass")
curl.setopt(pycurl.VERBOSE, 1)

buffer = BytesIO()
curl.setopt(pycurl.WRITEDATA, buffer)
curl.perform()
curl.close()

Performance Benchmarking

import pycurl
from io import BytesIO
import statistics

times = []
for _ in range(10):
    curl = pycurl.Curl()
    curl.setopt(pycurl.URL, "https://api.ipify.org")
    curl.setopt(pycurl.PROXY, "PROXYHOST:PORT")
    curl.setopt(pycurl.PROXYUSERPWD, "user:pass")
    
    buffer = BytesIO()
    curl.setopt(pycurl.WRITEDATA, buffer)
    curl.perform()
    
    times.append(curl.getinfo(pycurl.TOTAL_TIME))
    curl.close()

print(f"Mean: {statistics.mean(times):.3f}s")
print(f"Median: {statistics.median(times):.3f}s")
print(f"Std dev: {statistics.stdev(times):.3f}s")

ProxyMesh Headers Reference

Send these headers to control proxy behavior:

X-ProxyMesh-Country - Route through a specific country (e.g., "US"). Only works with world proxy or open proxy
X-ProxyMesh-IP - Request a specific outgoing IP address
X-ProxyMesh-Not-IP - Exclude specific IPs from rotation

The proxy returns X-ProxyMesh-IP in the response with the IP address used.

Resources

Related Python Proxy Guides

Explore proxy configuration for other Python HTTP libraries:

urllib3 - Pure Python with connection pooling
Requests - Simple, elegant API
aiohttp - Async HTTP for concurrent requests

Start Free Trial