Proxy Examples

Example code for using proxy servers in different programming languages. Currently we have examples for these languages:

• Python
• JavaScript / Node.js
• Ruby
• PHP

Python Proxy Examples

Installation:

pip install -r python/requirements.txt

pycurl needs libcurl and curl-config (for example Debian/Ubuntu: libcurl4-openssl-dev). The test runner skips pycurl-* examples when pycurl is not installed, and skips scrapy-proxy when import scrapy fails (for example a broken cryptography / cffi install).

Running Examples:

# Required: Set your proxy URLexport PROXY_URL='http://user:pass@proxy.example.com:8080'# Optional: Target URL (default: https://api.ipify.org?format=json)export TEST_URL='https://httpbin.org/ip'# Optional: Print one response headerexport RESPONSE_HEADER='X-ProxyMesh-IP'# Single example
python python/requests-proxy.py
# All examples as tests
python python/run_tests.py
# Specific examples (substring match, like the JS runner)
python python/run_tests.py requests httpx

Examples:

Library	Example	Description
requests	requests-proxy.py	Basic GET with proxies=
requests	requests-session-proxy.py	Session with pooled connections
urllib3	urllib3-proxy.py	ProxyManager
aiohttp	aiohttp-proxy.py	Async client, proxy= on the request
httpx	httpx-proxy.py	Sync client, proxy= on the client
httpx	httpx-async-proxy.py	Async client
pycurl	pycurl-proxy.py	libcurl via setopt (PROXY, WRITEDATA, etc.)
cloudscraper	cloudscraper-proxy.py	Requests-based scraper with proxies
autoscraper	autoscraper-proxy.py	Offline html= demo (matches upstream tests); README shows request_args + proxies for live URLs
Scrapy	scrapy-proxy.py	scrapy runspider with meta['proxy']

Other Python scripts

• requests-random-proxy.py - Random proxy rotation

Note: Like the Ruby, JavaScript, and PHP examples here, these scripts use each library's normal proxy options only. Most of them do not send custom headers on the HTTPS CONNECT tunnel or surface proxy CONNECT response headers. For that, see python-proxy-headers or scrapy-proxy-headers.

JavaScript / Node.js Proxy Examples

Installation:

cd javascript
npm install

Running Examples:

# Required: Set your proxy URLexport PROXY_URL='http://user:pass@proxy.example.com: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 got

Examples:

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.

Ruby Proxy Examples

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 install

Running examples:

# Required: set your proxy URLexport PROXY_URL='http://user:pass@proxy.example.com:8080'# Optional: target URL (default: https://api.ipify.org?format=json)export TEST_URL='https://httpbin.org/ip'# Optional: print one response headerexport 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 typhoeus

Examples:

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.

PHP Proxy Examples

Installation:

cd php
composer install

Running Examples:

# Required: Set your proxy URLexport PROXY_URL='http://user:pass@proxy.example.com:8080'# Run a single example
php php/guzzle_proxy.php
# Run all examples as tests
php php/run_tests.php

Examples:

Library	Example	Description
cURL	curl_proxy.php	PHP's built-in HTTP client (libcurl)
Guzzle	guzzle_proxy.php	Most popular PHP HTTP client
Symfony HttpClient	symfony_http_client_proxy.php	Modern PSR-18 HTTP client
Buzz	buzz_proxy.php	Simple PSR-18 HTTP client
PHP Streams	streams_proxy.php	Built-in PHP streams (file_get_contents)
Amp HTTP	amphp_proxy.php	Async HTTP client

Note: See php-proxy-headers for extensions that add custom proxy header support.

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 install

Running examples:

# Required: set your proxy URLexport PROXY_URL='http://user:pass@proxy.example.com:8080'# Optional: target URL (default: https://api.ipify.org?format=json)export TEST_URL='https://httpbin.org/ip'# Optional: print one response headerexport 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 typhoeus

Examples:

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.

Related Documentation

More examples and language-specific proxy-header tooling:

Python

• python-proxy-headers on PyPI
• python-proxy-headers Documentation
• python-proxy-headers GitHub

JavaScript / Node.js

• javascript-proxy-headers GitHub
• javascript-proxy-headers on npm
• javascript-proxy-headers on JSR

Ruby

• Ruby examples in this repository: ruby/

Contributing

Contributions are welcome for all supported languages in this repository (Python, JavaScript, Ruby, and PHP), 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.