Example code for using proxy servers in different programming languages. Currently we have examples for these languages:
- Python
- JavaScript / Node.js
- Ruby
The python-proxy-headers library enables sending custom headers to proxy servers and receiving proxy response headers. This is essential for services like ProxyMesh that use custom headers for country selection and IP assignment.
Installation:
pip install python-proxy-headersRunning Examples:
All examples read proxy configuration from environment variables:
# Required: Set your proxy URL
export PROXY_URL='http://user:[email protected]:8080'
# Optional: Custom test URL (default: https://api.ipify.org?format=json)
export TEST_URL='https://httpbin.org/ip'
# Optional: Send a custom header to the proxy
export PROXY_HEADER='X-ProxyMesh-Country'
export PROXY_VALUE='US'
# Optional: Read a specific header from the response
export RESPONSE_HEADER='X-ProxyMesh-IP'
# Run a single example
python python/requests-proxy-headers.py
# Run all examples as tests
python python/run_tests.py
# Run specific examples
python python/run_tests.py requests-proxy-headers httpx-proxy-headersExamples:
| Library | Example | Description |
|---|---|---|
| requests | requests-proxy-headers.py | Simple HTTP requests with proxy headers |
| requests | requests-proxy-headers-session.py | Session-based requests for connection pooling |
| urllib3 | urllib3-proxy-headers.py | Low-level HTTP client with proxy headers |
| aiohttp | aiohttp-proxy-headers.py | Async HTTP client with proxy headers |
| httpx | httpx-proxy-headers.py | Modern HTTP client with proxy headers |
| httpx | httpx-async-proxy-headers.py | Async httpx with proxy headers |
| pycurl | pycurl-proxy-headers.py | libcurl bindings with proxy headers |
| pycurl | pycurl-proxy-headers-lowlevel.py | Low-level pycurl integration |
| cloudscraper | cloudscraper-proxy-headers.py | Cloudflare bypass with proxy headers |
| autoscraper | autoscraper-proxy-headers.py | Automatic web scraping with proxy headers |
Note: Most Python HTTP libraries do not expose custom headers on HTTPS
CONNECTtunneling by default. These examples use python-proxy-headers adapters to send proxy headers and read proxy response headers consistently.
- requests-proxy.py - Basic proxy usage with requests
- requests-random-proxy.py - Random proxy rotation
- scrapy-proxy-headers.py - Scrapy spider with proxy headers
Installation:
cd javascript
npm installRunning Examples:
# Required: Set your proxy URL
export PROXY_URL='http://user:[email protected]:8080'
# Run a single example
node javascript/axios-proxy.js
# Run all examples as tests
node javascript/run_tests.js
# Run specific examples
node javascript/run_tests.js axios gotExamples:
| Library | Example | Description |
|---|---|---|
| axios | axios-proxy.js | Popular promise-based HTTP client |
| node-fetch | node-fetch-proxy.js | Fetch API for Node.js |
| got | got-proxy.js | Human-friendly HTTP client |
| undici | undici-proxy.js | Fast HTTP client (powers Node.js fetch) |
| superagent | superagent-proxy.js | Flexible HTTP client |
| needle | needle-proxy.js | Lean HTTP client |
| puppeteer | puppeteer-proxy.js | Headless Chrome automation |
| playwright | playwright-proxy.js | Browser automation |
| cheerio | cheerio-proxy.js | HTML parsing with node-fetch |
| ky | ky-proxy.js | Fetch wrapper (node-fetch + agent) |
| wretch | wretch-proxy.js | Fetch wrapper (polyfill) |
| make-fetch-happen | make-fetch-happen-proxy.js | npm-style fetch |
| typed-rest-client | typed-rest-client-proxy.js | REST client (built-in proxy option) |
Note: None of these libraries currently support sending custom headers to the proxy during HTTPS CONNECT tunneling or reading proxy response headers. See javascript-proxy-headers for extension modules that add this capability.
Installation:
These examples use Bundler. Install Ruby development headers and libcurl first so native extensions can compile (Debian/Ubuntu: ruby-dev and libcurl4-openssl-dev; Fedora: ruby-devel and libcurl-devel).
cd ruby
bundle installRunning examples:
# Required: set your proxy URL
export PROXY_URL='http://user:[email protected]:8080'
# Optional: target URL (default: https://api.ipify.org?format=json)
export TEST_URL='https://httpbin.org/ip'
# Optional: print one response header
export RESPONSE_HEADER='X-ProxyMesh-IP'
# Single example (from ruby/)
bundle exec ruby faraday-proxy.rb
# All examples as tests
bundle exec ruby run_tests.rb
# Specific examples
bundle exec ruby run_tests.rb faraday typhoeusExamples:
| Library | Example | Description |
|---|---|---|
| Net::HTTP (stdlib) | net-http-proxy.rb | Low-level HTTP with proxy (Net::HTTP.new + proxy host/port/user/pass) |
| Faraday | faraday-proxy.rb | Middleware-style client; Faraday.new(proxy: url) |
| HTTParty | httparty-proxy.rb | Simple API; http_proxyaddr / http_proxyport / credentials |
| HTTP.rb | http-rb-proxy.rb | Lightweight DSL; proxy via HTTP.via(host, port, user, pass) |
| RestClient | rest-client-proxy.rb | Simple REST API; proxy via RestClient.proxy = url |
| Typhoeus | typhoeus-proxy.rb | libcurl via Ethon; proxy: URL on the request |
| Excon | excon-proxy.rb | Fast client; Excon.get(url, proxy: url) |
| HTTPClient | httpclient-proxy.rb | LWP-like client; pass full proxy URL to HTTPClient.new |
| Mechanize | mechanize-proxy.rb | Crawling / forms; set_proxy(host, port, user, password) |
| Nokogiri | nokogiri-proxy.rb | Parse HTML after a proxied Net::HTTP fetch |
Libraries above are actively maintained on RubyGems (releases within the last year as of early 2026). Like most high-level Ruby HTTP clients, they do not expose custom headers on the HTTPS CONNECT tunnel to the proxy or proxy response headers; for ProxyMesh-style custom proxy headers, lower-level clients or a dedicated helper library may be required.
More examples and language-specific proxy-header tooling:
- Ruby examples in this repository: ruby/
Contributions are welcome for all supported languages in this repository (Python, JavaScript, and Ruby), as well as new language examples.
When opening a Pull Request:
- Follow the existing file naming and environment variable patterns (
PROXY_URL,TEST_URL, and optional response/proxy header variables). - Include runnable examples and update the language section in this README.
- Add or update the language test runner (
run_tests) where applicable.