Configuring a reqwest Proxy for Rust HTTP Clients
By the ProxyV4 Engineering Team · 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.
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::httpsdescribes the target scheme. The proxy URL itself still usually starts withhttp://, because the client talks plain HTTP to the proxy and opens aCONNECTtunnel 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.
| Constructor | Applies to | Typical use |
|---|---|---|
Proxy::all(url) | Both http:// and https:// targets | The normal choice for a single proxy |
Proxy::http(url) | Only http:// targets | Splitting plain HTTP onto a different route |
Proxy::https(url) | Only https:// targets | Proxying 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_PROXYorhttp_proxyforhttp://targets;HTTPS_PROXYorhttps_proxyforhttps://targets.ALL_PROXYorall_proxyfor both. If both a specific and anALL_PROXYvariable are set, the specific one wins.NO_PROXYis checked first, thenno_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 thesocksfeature 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