15% off your first purchase with code WELCOME15, up to 25 GB.

See pricing
ARC Proxies

Integration · HTTP clients

How to use a proxy with curl

curl uses a proxy with -x (--proxy) and authenticates with -U (--proxy-user): curl -x http://host:port -U user:pass https://example.com. It is the fastest way to check a username, a country or a sticky session before it goes into a crawler, because one command shows the exit IP and the proxy's answer.

Reviewed 30 Oct 2026

your proxy, as a URL
http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000

The short answer

  • -x sets the proxy, -U user:pass the proxy credentials; both can also live in one URL.
  • -w '%{http_connect}' prints the proxy's answer to the CONNECT request: 200 is fine, 407 means wrong credentials.
  • socks5h:// resolves hostnames at the proxy; socks5:// resolves them on your machine.
  • --retry covers timeouts and 408, 429, 500, 502, 503, 504, not a 407.

Setup

Set up curl with a proxy, step by step

  1. 01

    Send one request and read the exit IP

    The echo service returns the address the target sees: a German residential exit for this username.

    shell
    curl -x http://proxy.arcproxies.io:8000 \  -U "USERNAME_pool-arcfast_country-de:PASSWORD" \  "https://api.ipify.org?format=json"
  2. 02

    Confirm a sticky session holds

    Run the same sticky username twice: both calls should print the same IP. Run the rotating username twice: the IPs may differ, because each curl run opens a new connection.

    shell
    for i in 1 2; do  curl -s -x http://proxy.arcproxies.io:8000 -U "USERNAME_pool-arcfast_country-de_session-k3f9a1x2_sesstime-10:PASSWORD" https://api.ipify.org; echodonefor i in 1 2; do  curl -s -x http://proxy.arcproxies.io:8000 -U "USERNAME_pool-arcfast_country-de:PASSWORD" https://api.ipify.org; echodone
  3. 03

    Check a country or city

    Change the tokens and compare. _country- is a lowercase ISO code; _city- comes from the published list, lowercased without spaces. An IP-geolocation lookup on the result is a rough check, since databases disagree at city level.

    shell
    curl -s -x http://proxy.arcproxies.io:8000 \  -U "USERNAME_pool-arcfast_country-gb_city-manchester:PASSWORD" \  https://api.ipify.org; echocurl -s -x http://proxy.arcproxies.io:8000 \  -U "USERNAME_pool-arcfast_country-us_city-losangeles:PASSWORD" \  https://api.ipify.org; echo
  4. 04

    Use SOCKS5 instead of HTTP

    Same port, same credentials, different scheme. socks5h:// lets the gateway resolve the hostname.

    shell
    curl -x "socks5h://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000" \  https://api.ipify.org
  5. 05

    Diagnose a failing proxy

    %{http_connect} is the proxy's answer to the CONNECT request, %{http_code} the site's answer. A 407 tunnel failure makes curl exit with an error (code 56 in curl 8.x) before the site is ever reached. -v shows the full exchange.

    shell
    curl -s -o /dev/null \  -w 'proxy=%{http_connect} site=%{http_code} exit=%{exitcode} time=%{time_total}s\n' \  -x http://proxy.arcproxies.io:8000 -U "USERNAME_pool-arcfast_country-de:PASSWORD" \  https://example.com/# proxy=200 site=200 exit=0  … fine# proxy=407 site=000 exit=56 … wrong username or password
  6. 06

    Timeouts and retries for scripts

    --connect-timeout bounds connection setup, --max-time the whole transfer. --retry retries timeouts and 408, 429, 500, 502, 503, 504, waiting one second and doubling, and honours Retry-After.

    shell
    curl --compressed \  --connect-timeout 10 --max-time 60 \  --retry 3 \  -x http://proxy.arcproxies.io:8000 -U "USERNAME_pool-arcfast_country-de:PASSWORD" \  "https://example.com/products?page=1"

Ways to give curl the proxy credentials

FormExampleNote
Separate flag-x http://host:port -U user:passClearest; curl hides the argument from process listings where it can
In the proxy URL-x http://user:pass@host:portPercent-encode @ as %40 and : as %3a in the password
Environmenthttps_proxy=http://user:pass@host:port curl …-x overrides it; handy for tools that call curl
Config fileproxy-user = "user:pass" in a file passed with -KKeeps the password out of shell history

curl's own manual warns that -U on the command line can still be seen briefly by other users on the same machine, and recommends reading credentials from a file.

HTTP proxy, CONNECT and HTTPS sites

For an https:// URL, curl asks the gateway to open an HTTP CONNECT tunnel to the site's port 443 and then runs TLS through it, so the gateway sees the hostname but not the request. For an http:// URL, curl sends the request to the proxy in absolute form instead. -p (--proxytunnel) forces a tunnel for plain HTTP too.

For a step-by-step method to confirm where an exit really is, including the limits of geolocation databases, see how to test a proxy's location.

Rotating vs sticky from the command line

Every curl invocation is a new connection, so a rotating username can return a new exit each time; several URLs in one invocation may reuse a connection and share one. Add _session-<handle>_sesstime-<minutes> to pin the exit across invocations. A sticky session is best effort: if the exit goes offline, the same handle returns a new IP.

The problem

Common pitfalls

Quoting the URL

In zsh and some other shells, an unquoted ? in a URL is a glob and the command fails before curl runs. Quote URLs with query strings.

socks5:// when you meant socks5h://

socks5:// resolves DNS locally, which can pick a regional server for your own location rather than the exit's. Use socks5h://.

Expecting --retry to fix a 407

A refused tunnel is not a transient error. Fix the credentials; retries will not help.

Forgetting --compressed

curl does not ask for compressed responses unless you pass --compressed. Through a per-GB proxy, that is bandwidth you pay for.

FAQ

Questions

Something not covered? Write to contact@arcproxies.io.

How do I use curl with a proxy that needs a username and password?

Use curl -x http://host:port -U username:password https://example.com, or put the credentials in the proxy URL: curl -x http://username:password@host:port https://example.com.

How do I check my proxy IP with curl?

Request an IP echo service through the proxy, for example curl -x http://host:port -U user:pass https://api.ipify.org. The response is the exit IP the target sees.

What is the difference between socks5 and socks5h in curl?

With socks5://, curl resolves the hostname itself and sends the IP to the proxy. With socks5h://, the proxy resolves the hostname. For geo-targeted work, socks5h:// keeps DNS consistent with the exit.

What does curl exit code 56 mean with a proxy?

Exit 56 is a failure receiving network data. With a proxy it often means the gateway refused the CONNECT tunnel; -w '%{http_connect}' shows the proxy's status, and 407 means the credentials were rejected.

Does curl --retry retry proxy errors?

It retries transient errors: timeouts and HTTP 408, 429, 500, 502, 503 and 504. A 407 from the proxy is not among them; --retry-all-errors would retry it, but wrong credentials stay wrong.

Sources & review

Last reviewed by the ARC Proxies team. Prices are read from the live catalog at build time.

  1. [1]curl: curl man page
  2. [2]everything curl: Proxies

Next

What people build with it

Use caseProxies for web scraping and data collectionA second provider that just works — Scrapy, requests, Crawlee or Playwright, self-serve, no sales call, bandwidth that never expires.Use caseProxies for QA, app and localisation testingSee your own site the way a user in Tokyo, São Paulo or Munich sees it — currency, language, consent banner, CDN edge and all — before they report it.GlossaryHTTP CONNECTHTTP CONNECT is the HTTP request method a client sends to a proxy to ask for a tunnel to a host and port; once the proxy answers with a 2xx status it blindly forwards bytes in both directions, which is how HTTPS passes through an HTTP proxy with TLS intact end to end (RFC 9110, section 9.3.6).GlossarySticky sessionA sticky session is a setting on a rotating proxy that keeps the same exit IP address for a chosen period, usually by attaching a session identifier to the connection, so a multi-step task appears to come from one address from start to finish.GuideHow to test a proxy's locationCheck a proxy's exit IP and geolocation with curl, why IP geolocation databases disagree, and how to verify what the target site actually sees.GuideHow to reduce proxy bandwidthCut proxy bandwidth by fetching HTML or JSON instead of rendering, blocking images and fonts, using compression, conditional requests and local caching.IntegrationPython requestsUse an authenticated proxy with Python requests: the proxies argument, sticky sessions per task, geo-targeting, SOCKS5 and retries that skip 407 errors.

Integrations

Other http clients

Python requestsUse an authenticated proxy with Python requests: the proxies argument, sticky sessions per task, geo-targeting, SOCKS5 and retries that skip 407 errors.HTTPXConfigure an authenticated proxy in HTTPX 0.28: the proxy= argument that replaced proxies=, mounts per domain, async clients, SOCKS5 and error handling.aiohttpUse an authenticated proxy with aiohttp: proxy= per request or per session, why proxy_auth is deprecated, SOCKS5 through aiohttp-socks, and 407 handling.AxiosUse an authenticated proxy with Axios in Node.js: the proxy option on 1.16.1+, https-proxy-agent for older versions, sticky sessions, SOCKS5 and 407s.Node.js fetchNode's built-in fetch has no proxy option. Use undici's ProxyAgent as the dispatcher, or NODE_USE_ENV_PROXY, with sticky sessions, SOCKS5 and 407 handling.GoRoute Go's net/http through an authenticated proxy: Transport.Proxy with url.UserPassword, a sticky session per request context, SOCKS5 and 407 checks.RubyUse an authenticated proxy in Ruby: Net::HTTP proxy arguments, Faraday proxy options, sticky sessions per task, geo-targeting and 407 handling.PHP GuzzleRoute PHP Guzzle and plain cURL through an authenticated proxy: the proxy option, sticky sessions, geo-targeting, retries that stop on a 407.Java HttpClientUse an authenticated proxy with java.net.http.HttpClient: ProxySelector, Authenticator, the Basic-over-CONNECT setting, sticky sessions and 407s.C# HttpClientUse an authenticated proxy in .NET: WebProxy and NetworkCredential on SocketsHttpHandler, a client per sticky session, SOCKS5 and 407 handling.Rust reqwestRoute Rust reqwest through an authenticated proxy: Proxy::all with basic_auth, a Client per sticky session, socks5h, timeouts and 407 errors.wgetRun GNU Wget through an authenticated proxy: https_proxy, --proxy-user, a .wgetrc for credentials, sticky sessions for mirrors and exit codes.PostmanSend Postman requests through an authenticated proxy: the custom proxy settings, Proxy auth, checking the exit IP, sessions, countries and Newman.DockerGive Docker containers and builds an authenticated proxy: HTTP_PROXY, HTTPS_PROXY and NO_PROXY, build args, Compose, and why the daemon proxy differs.

Get started

Get credentials and paste them in.

Sign up, buy a gigabyte, generate a username in the dashboard. Code WELCOME15 takes 15% off your first purchase; bandwidth never expires.

Create your accountQuestions first? contact@arcproxies.io