Configuring a reqwest Proxy for Rust HTTP Clients

· Updated:

To send reqwest traffic through a proxy, build a reqwest::Proxy with Proxy::all("http://ip:port"), add credentials with .basic_auth(user, pass), and pass it to Client::builder().proxy(...). SOCKS5 works the same way once you enable the socks Cargo feature. The examples target reqwest 0.13, the current release, and the proxy API is unchanged from 0.12.

Unmetered IPs for Rust crawlers

A minimal reqwest proxy with credentials

Start with the dependencies. Proxy support is part of the default build, so plain HTTP(S) proxying needs no extra features:

[dependencies]
reqwest = "0.13"
tokio = { version = "1", features = ["full"] }

Then build a client with one proxy, set timeouts, and fetch an IP echo endpoint to prove the route works:

use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let proxy = reqwest::Proxy::all("http://203.0.113.10:PORT")?
        .basic_auth("USER", "PASS");

    let client = reqwest::Client::builder()
        .proxy(proxy)
        .connect_timeout(Duration::from_secs(10))
        .timeout(Duration::from_secs(30))
        .build()?;

    let body = client
        .get("https://proxyv4.com/api/my-ip")
        .send()
        .await?
        .error_for_status()?
        .text()
        .await?;

    println!("{body}"); // JSON with the exit IP
    Ok(())
}

The printed JSON should contain the proxy's address. Keep the Client around: it owns a connection pool, and building a client per request wastes both the pool and the TLS setup.

Credentials in the URL instead of basic_auth

reqwest also accepts http://USER:[email protected]:PORT and turns the user info into a Proxy-Authorization header. Percent-encode reserved characters such as @, : and # in that form. With .basic_auth() you pass the raw strings and skip encoding entirely, which is why it is the safer choice for generated passwords.

Using the blocking client

For a CLI tool without an async runtime, enable the blocking feature and use reqwest::blocking::Client::builder(). The .proxy() call and the Proxy type are identical.

Proxy::all, Proxy::http and Proxy::https

The three constructors differ in which requests they intercept, and the naming misleads many people at first.

  • Proxy::https describes the target scheme. The proxy URL itself still usually starts with http://, because the client talks plain HTTP to the proxy and opens a CONNECT tunnel through it.
  • If you add several proxies, reqwest checks them in order and uses the first that matches the request.
  • Adding any proxy with .proxy() disables the automatic system proxy, so environment variables stop applying to that client.
ConstructorApplies toTypical use
Proxy::all(url)Both http:// and https:// targetsThe normal choice for a single proxy
Proxy::http(url)Only http:// targetsSplitting plain HTTP onto a different route
Proxy::https(url)Only https:// targetsProxying TLS traffic while letting plain HTTP go direct

Turning on the reqwest socks5 feature

SOCKS support is behind a non-default feature flag called socks. Add it in Cargo.toml:

[dependencies]
reqwest = { version = "0.13", features = ["socks"] }

After that, a SOCKS URL goes through the same constructors. Credentials embedded in the URL are used for SOCKS5 username and password login:

let proxy = reqwest::Proxy::all("socks5h://USER:[email protected]:PORT")?;

let client = reqwest::Client::builder()
    .proxy(proxy)
    .build()?;

socks5h keeps DNS on the proxy side

reqwest recognizes socks4, socks4a, socks5 and socks5h. With socks5:// your machine resolves the target hostname and sends the proxy an IP; with socks5h:// the hostname goes to the proxy and it resolves it. Use socks5h so lookups match the proxy's location and do not depend on your host's resolver.

Forgetting the feature

Without the socks feature, reqwest does not know how to speak SOCKS, and the request fails with a connection or tunnel error that never mentions the missing feature. If a SOCKS URL fails while the same proxy works in HTTP mode, check Cargo.toml and cargo tree -e features -i reqwest before anything else.

System proxies, environment variables and NO_PROXY

A client built without .proxy() uses the system proxy by default. On every platform that means environment variables; with the default system-proxy feature, reqwest also reads the Windows and macOS system settings.

  • HTTP_PROXY or http_proxy for http:// targets; HTTPS_PROXY or https_proxy for https:// targets.
  • ALL_PROXY or all_proxy for both. If both a specific and an ALL_PROXY variable are set, the specific one wins.
  • NO_PROXY is checked first, then no_proxy. Entries can be hostnames, domain suffixes or CIDR ranges.
  • A SOCKS URL in any of these variables (for example https_proxy=socks5h://...) also needs the socks feature compiled in.

Exclusions for an explicit proxy

Because an explicit proxy switches the environment off, NO_PROXY no longer applies to it automatically. Attach an exclusion list to the proxy yourself, or opt out of proxying altogether for a client that talks to internal services:

use reqwest::{NoProxy, Proxy};

let proxy = Proxy::all("http://203.0.113.10:PORT")?
    .basic_auth("USER", "PASS")
    .no_proxy(NoProxy::from_string("localhost,127.0.0.1,.internal.example"));

// Or reuse whatever NO_PROXY / no_proxy says:
// .no_proxy(NoProxy::from_env());

// A client that must never use a proxy, whatever the environment says:
let direct = reqwest::Client::builder().no_proxy().build()?;

Running a Rust crawler across several IPs

reqwest has no built-in rotation, and you rarely want it hidden inside the client anyway. The clean pattern is one Client per proxy, built at startup from your proxy list, with your scheduler choosing which client handles each job:

use reqwest::{Client, Proxy};

fn client_for(line: &str) -> Result<Client, Box<dyn std::error::Error>> {
    // line format: ip:port:user:pass
    let parts: Vec<&str> = line.trim().splitn(4, ':').collect();
    let [ip, port, user, pass] = parts[..] else {
        return Err(format!("bad proxy line: {line}").into());
    };
    let proxy = Proxy::all(format!("http://{ip}:{port}"))?.basic_auth(user, pass);
    Ok(Client::builder().proxy(proxy).build()?)
}

// Build once at startup, then pick clients[i % clients.len()] per job.
// Client is cheap to clone: clones share the same connection pool.

Keeping one client per IP also keeps connection reuse honest: keep-alive sockets stay bound to the proxy that opened them. Pace each client separately so a single address does not carry the whole crawl, and respect each site's terms and robots rules.

Where a static IPv4 pool fits a Rust crawler

Rust crawlers tend to move a lot of data per IP, which is where per-GB pricing hurts. ProxyV4 private IPv4 and static ISP proxies are priced per IP with traffic that is never metered, so the byte count of a crawl does not change the bill. Each IP has one tenant for the whole term and keeps its address on renewal, which matters when a target remembers a session or rate budget per IP. The web scraping proxy guide covers sizing a pool and pacing requests.

Every proxy accepts HTTP(S) and SOCKS5 with username and password, and you pick HTTP only, SOCKS5 only or both on the same port per order; switching can move the port, so reload the list afterwards. This setup suits crawls that want stable identities spread over datacenter IPv4 in seven countries. It does not suit jobs that need a new IP on every request, since rotating proxies are not on sale, or targets that accept only mobile addresses. IPv6 proxies are a separate product that only works on IPv6-ready sites. Order one IP from live pricing, run the crawler against it, then scale; technical failures such as an IP that will not connect fall under the refund policy as balance credit.

Decoding reqwest proxy errors

reqwest's top-level message is usually just error sending request for url (...). The useful part is further down the error's source chain, so print the whole chain before guessing:

fn report(err: &reqwest::Error) {
    eprintln!("error: {err}");
    let mut source = std::error::Error::source(err);
    while let Some(cause) = source {
        eprintln!("  caused by: {cause}");
        source = cause.source();
    }
    if err.is_connect() { eprintln!("  (failed while connecting)"); }
    if err.is_timeout() { eprintln!("  (timed out)"); }
}

tunnel error: proxy authorization required

The proxy answered the CONNECT request with 407. The username or password is wrong, contains unencoded characters in URL form, or was never attached because .basic_auth() was called on a different Proxy value. For http:// targets you get a normal response with status 407 instead, which error_for_status() turns into an error. More causes are listed in the 407 troubleshooting page.

tunnel error: unsuccessful, refused or timed out

unsuccessful means the proxy answered CONNECT with something other than 200 or 407, or the endpoint is not an HTTP proxy at all (a SOCKS-only port, for example). Connection refused in the chain points to a wrong port or a proxy that moved after a mode switch; is_timeout() without a response points to a firewall. Check the same ip:port:user:pass in the proxy checker to separate code problems from network ones.

Frequently asked questions

Does reqwest read the HTTP_PROXY environment variable?

Yes, by default a client uses HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and their lowercase forms, plus NO_PROXY. Calling .proxy() or .no_proxy() on the builder turns that off.

Why does my reqwest SOCKS5 proxy not work?

The most common cause is a missing socks feature in Cargo.toml. The next is using socks5:// when the target hostname only resolves correctly from the proxy, which socks5h:// fixes.

Can I set a different proxy per request in reqwest?

No, proxies belong to the Client. Build one client per proxy and choose the client per request; clones of a client are cheap and share its pool.

Should a Rust crawler use HTTP or SOCKS5 mode?

For HTTPS scraping both carry the same TLS traffic, so HTTP mode avoids the extra feature flag. With ProxyV4 you can enable both on one port and switch per client by changing only the URL scheme.

Is bandwidth limited on proxies used for crawling?

Traffic on ProxyV4 private IPv4 and static ISP proxies is not metered or billed, so large crawls cost the same per IP as small ones.

Unmetered IPs for Rust crawlers

Private IPv4 and static ISP proxies with traffic that is never metered, one tenant per IP, and HTTP(S) plus SOCKS5 login. Start with a single IP and grow the pool once your crawler runs clean.

Get a static IP

Related articles

Proxies by platform
Proxies for web scraping: a fixed pool of IPs with unmetered traffic
Web scraping proxies for Python, Scrapy, Playwright and Selenium: a pool of private IPv4 and static ISP addresses, unlimited bandwidth, flat per-IP pricing.
Knowledge base
Checking a Proxy: A Three-Pass Test Before Real Work
Check a proxy in three passes: does it connect, which IP and country do websites see, and is the browser leak-free. Free checker, curl commands and error fixes.
Proxy setup
Python requests through an authenticated proxy, step by step
Send Python requests through an authenticated HTTP(S) proxy: build the proxies dict, attach it to a Session, encode odd passwords, rotate a list, check the IP.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Proxy setup
Set up your proxy, tool by tool
Proxy setup instructions you can follow with the dashboard open: antidetect browsers, operating systems, browser extensions and scraping libraries, all with authenticated HTTP(S) or SOCKS5.
Knowledge base
Routing Ruby HTTP Requests Through an Authenticated Proxy
Ruby Net::HTTP proxy setup with a username and password, plus Faraday and HTTParty options, the https_proxy quirk, SOCKS via socksify and common exceptions.
Knowledge base
Setting Up wget Behind a Proxy That Needs a Login
Set a wget proxy username and password with flags, http_proxy and https_proxy variables or wgetrc, then fix 407 errors and handle SOCKS5 downloads.
Knowledge base
How to Run git clone Through a Proxy (HTTPS and SSH Remotes)
Git clone through a proxy: set http.proxy globally, per repo or per host, use socks5h for HTTPS remotes, and route git over SSH with a ProxyCommand.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.