How to Use cURL With a Proxy: HTTP, HTTPS, SOCKS5, and Authentication

To use cURL with a proxy, add --proxy protocol://host:port to the command. If the proxy requires a username and password, add --proxy-user 'username:password'. For a SOCKS5 proxy that should resolve the destination hostname, use the socks5h:// scheme.

TL;DR

• Use --proxy or -x to specify the proxy server.
• Use --proxy-user or -U for HTTP, HTTPS, and SOCKS5 proxy credentials.
• Use socks5h:// when the SOCKS5 proxy should resolve the destination hostname.
• An HTTP proxy can carry traffic to an HTTPS website through a CONNECT tunnel.
• An HTTPS proxy is different: TLS also protects the connection from cURL to the proxy.
• Use http_proxy, HTTPS_PROXY, ALL_PROXY, and NO_PROXY to configure proxy behavior through environment variables.
• Verify the setup by comparing the exit IP with and without the proxy, then use --verbose if the request fails.
• Keep credentials out of source code, Git, shared shell history, and unredacted debug logs.

cURL supports HTTP, HTTPS, SOCKS4, SOCKS4a, SOCKS5, and SOCKS5-hostname proxy connections. That makes it useful for API testing, regional content checks, web scraping, corporate network access, and command-line debugging.

The proxy protocol should match the application and provider. HTTP proxies are usually the simplest choice for websites and APIs. SOCKS5 proxies provide a more general relay and can move destination-hostname resolution to the proxy.

For a deeper protocol comparison, see our guide to HTTP vs SOCKS5 proxies. If the proxy is part of a data-collection workflow, the web scraping proxies guide explains how the network layer fits into a larger pipeline.

Run this first if you are not sure whether cURL is installed:

For a broader introduction to the tool, read What is cURL?. This guide stays focused on proxy configuration.

What Is the Fastest Way to Use cURL With a Proxy?

The fastest setup is to pass the proxy URL with --proxy and, when required, pass its credentials with --proxy-user. These three examples cover the most common cURL proxy configurations.

Authenticated HTTP Proxy

Authenticated SOCKS5 Proxy With Remote DNS

Proxy Credentials Inside the URL

Replace the hostname, port, username, and password with the credentials from your proxy provider or Proxidize dashboard.

The inline-URL format is convenient for a quick test, but --proxy-user is easier to read and keeps credentials out of copied proxy URLs. Neither approach makes a literal command-line password fully private. The security section below explains safer options for scripts and production systems.

In short: Use --proxy for the endpoint, --proxy-user for credentials, and an IP-check endpoint to confirm that the request exits through the proxy.

Using Proxidize Proxies With cURL

Proxidize residential and mobile proxies work with the same authenticated cURL syntax:

Copy the proxy hostname, port, username, and password from the Proxidize dashboard, then replace the placeholders in the command.

You can use this setup with residential proxies for broad geographic coverage or mobile proxies for carrier-based 4G and 5G IPs. The IP-check request confirms which exit IP cURL is using.

What Is the cURL Proxy Syntax?

The general cURL proxy syntax has three parts: the proxy endpoint, optional proxy credentials, and the destination URL.

The proxy scheme and destination scheme describe different connections. In this command, cURL speaks HTTP to the proxy but requests an HTTPS destination:

The official cURL proxy documentation supports the following proxy schemes:

If the scheme is omitted, cURL treats the endpoint as an HTTP proxy. Specifying the scheme and port explicitly is clearer and prevents a SOCKS endpoint from being interpreted as HTTP.

In short: The scheme before the proxy hostname controls how cURL reaches the proxy. The scheme in the final URL controls how cURL communicates with the destination.

How Do You Use an HTTP Proxy With cURL?

Use an HTTP proxy by passing http://proxy-host:port to --proxy or its short form, -x. The same syntax works whether the destination URL uses HTTP or HTTPS.

HTTP Proxy Without Authentication

The short form is equivalent:

HTTP Proxy With Authentication

In these commands:

1. cURL connects to proxy.example.com on port 8080.
2. cURL authenticates to the proxy when credentials are present.
3. The proxy creates or forwards the request to example.com.
4. The response returns to cURL through the proxy.

HTTP proxies are a practical default for websites, REST APIs, command-line tests, and web scraping clients because the traffic is already HTTP-based.

In short: Use curl -x http://host:port URL for an HTTP proxy. Add --proxy-user only when the endpoint requires authentication.

What Is the Difference Between an HTTP Proxy to an HTTPS Website and an HTTPS Proxy?

An HTTP proxy carrying traffic to an HTTPS website is not the same as an HTTPS proxy. The target URL scheme describes the destination connection, while the proxy URL scheme describes the connection between cURL and the proxy.

HTTP Proxy Carrying HTTPS Website Traffic

For an HTTPS destination, cURL normally sends the HTTP CONNECT method to the proxy. After the proxy accepts the tunnel, cURL performs the destination TLS handshake through it.

The official cURL HTTP proxy guide documents this HTTPS-over-HTTP-proxy behavior.

You do not need to add --proxytunnel for a normal HTTPS destination through an HTTP proxy. cURL uses CONNECT for that case automatically.

TLS Connection to an HTTPS Proxy

Here, TLS protects the cURL-to-proxy connection as well. If the destination is also HTTPS, cURL then establishes the destination’s protected connection through the proxy path.

An HTTPS proxy does not make an HTTP destination end-to-end encrypted. Use an HTTPS destination whenever the target supports it.

In short: https://example.com secures the destination session. --proxy https://proxy.example.com secures the cURL-to-proxy connection. They protect different parts of the route.

How Do You Use an HTTPS Proxy With cURL?

Use an HTTPS proxy by giving --proxy an https:// endpoint. cURL verifies the proxy’s TLS certificate separately from the destination website’s certificate.

HTTPS Proxy Without Authentication

HTTPS Proxy With Authentication

HTTPS Proxy With a Private or Self-Signed CA

The preferred fix is to supply the CA certificate that should be trusted for the proxy:

--proxy-cacert verifies the HTTPS proxy with the specified CA bundle. It is separate from --cacert, which changes trust for the destination server.

For a short, controlled diagnostic only, certificate verification for the proxy can be disabled:

--proxy-insecure disables certificate verification for the connection to the HTTPS proxy. It can expose the connection to impersonation and man-in-the-middle attacks.

Do not use it as a permanent production fix. Install the correct CA or use --proxy-cacert instead.

These options are easy to confuse:

See the cURL SSL certificate guide before disabling either form of verification.

In short: Prefer --proxy-cacert for an internal HTTPS proxy. Reserve --proxy-insecure for temporary diagnostics in a controlled environment.

How Do You Use a SOCKS5 Proxy With cURL?

Use a SOCKS5 proxy by passing a socks5:// or socks5h:// URL to --proxy. Use --proxy-user when the SOCKS5 endpoint requires username-and-password authentication.

SOCKS5 Proxy Without Authentication

The equivalent dedicated option is:

SOCKS5 Proxy With Authentication

or:

Important: --socks5-user and --socks5-password are not valid cURL command-line options. Use --proxy-user for SOCKS5 proxy credentials. The official cURL proxy authentication guide applies --proxy-user to both HTTP and SOCKS proxies.

SOCKS5 is useful when an application needs a general TCP relay or proxy-side destination DNS rather than HTTP-specific proxy behavior. For ordinary website and API requests, an HTTP proxy is often simpler.

In short: Use socks5h://host:port with --proxy-user. Do not use the nonexistent --socks5-user or --socks5-password flags.

What Is the Difference Between socks5:// and socks5h:// in cURL?

socks5:// makes cURL resolve the destination hostname locally. socks5h:// sends the destination hostname to the SOCKS5 proxy so the proxy resolves it.

Local Destination DNS Resolution

Proxy-Side Destination DNS Resolution

The h means hostname resolution is delegated to the proxy. The official cURL SOCKS proxy documentation makes the same local-versus-proxy distinction.

Use socks5h:// when local destination DNS could:

• Expose the requested destination hostname.
• Return a location-dependent address that does not match the proxy region.
• Fail because the hostname is only resolvable from the proxy’s network.

This setting applies to the destination hostname. cURL still has to locate and connect to the proxy itself, and other applications or requests on the device may still use local DNS.

Remote destination DNS is useful, but it is not a guarantee of complete anonymity.

In short: Choose socks5h:// when the SOCKS5 proxy should resolve the destination. Choose socks5:// when the cURL client should resolve it first.

How Do You Authenticate a Proxy in cURL?

Use --proxy-user 'username:password' to authenticate to HTTP, HTTPS, and SOCKS5 proxies. For HTTP-family proxies, cURL also supports Basic, Digest, NTLM, Negotiate, and automatic authentication-method selection.

Basic Proxy Authentication

HTTP Basic is cURL’s default proxy authentication method:

You can request it explicitly with --proxy-basic, but that is normally unnecessary.

Automatically Select an HTTP Proxy Authentication Method

--proxy-anyauth lets cURL inspect the proxy’s authentication challenge and select a supported method. It can add a request-response round trip.

If the proxy provider specifies the required authentication method, selecting it directly is more predictable.

Digest Proxy Authentication

NTLM Proxy Authentication

The single quotes preserve the backslash in Bash and similar shells. Quoting rules differ between shells, so adjust the credential string for the environment in which the command runs.

Negotiate or SPNEGO Proxy Authentication

Negotiate and NTLM support can depend on how cURL was built. Run curl --version and review the listed features if either option is rejected.

Proxy authentication and destination-server authentication are separate:

If the proxy returns 407 Proxy Authentication Required, confirm the credentials and required authentication method. The error code 407 guide covers the full diagnostic process.

In short: Use --proxy-user for the proxy, not --user. Advanced --proxy-* authentication flags apply to HTTP and HTTPS proxies, while SOCKS5 username-and-password authentication still uses --proxy-user.

How Do You Set a cURL Proxy With Environment Variables?

cURL reads scheme-specific proxy environment variables, ALL_PROXY, and NO_PROXY. Environment variables are useful when several cURL commands in the same shell or job should share a proxy configuration.

Linux and macOS

Set a proxy for HTTP destination URLs:

Set a proxy for HTTPS destination URLs:

Then run cURL normally:

HTTPS_PROXY means “use this proxy for HTTPS destination URLs.” The value can still start with http:// when the proxy itself uses HTTP.

The environment-variable name describes the destination scheme. The value’s scheme describes the proxy connection.

Use one fallback proxy for supported destination protocols:

A scheme-specific variable takes precedence over ALL_PROXY for its scheme.

Exclude selected hosts and networks:

Use a proxy variable for one command only:

Remove the variables from the current shell when they are no longer needed:

Windows PowerShell

Remove a variable from the PowerShell session with:

Using curl.exe avoids ambiguity on Windows systems where curl may resolve to a PowerShell alias instead of the cURL executable.

The official cURL environment-variable guide documents two important rules:

• http_proxy must be lowercase. cURL intentionally does not accept uppercase HTTP_PROXY.
• Other variables, such as HTTPS_PROXY, commonly work in uppercase or lowercase forms.

NO_PROXY accepts comma-separated hostnames, domain suffixes, IP addresses, and supported CIDR ranges. A single * disables proxy use for every host.

Environment variables are configuration, not a secrets vault. Values may be inherited by child processes or exposed by logs and diagnostic tools.

Inject credentials from a secret manager or use a protected cURL config file instead of storing them permanently in a shared shell profile or repository.

In short: Use a scheme-specific variable when only one destination protocol needs a proxy, ALL_PROXY as a fallback, and NO_PROXY for direct-connection exceptions.

How Do You Save cURL Proxy Settings in a Config File or .curlrc?

Use --config to read reusable cURL options from a file. Use .curlrc only when the settings should apply automatically to most cURL commands for that user.

Create a named file such as proxy.conf:

Load it explicitly:

The official cURL config-file documentation allows long option names without their leading dashes. Each option and its value must appear on the same physical line.

cURL also searches standard user configuration locations for a default file, including:

• $CURL_HOME/.curlrc
• $XDG_CONFIG_HOME/curlrc
• $HOME/.curlrc

Windows uses corresponding user-profile and application-data locations.

A named config file is often safer operationally than a global .curlrc because it makes proxy use explicit. A global proxy setting can affect unrelated cURL commands and make troubleshooting harder.

A config file containing credentials is still a plaintext secret. On a Unix-like system, restrict it to the owner:

Also:

• Add the file to the relevant .gitignore.
• Keep it out of build artifacts.
• Do not include it in container images.
• Apply an equivalent restrictive access-control list on Windows.
• Rotate the credentials if the file is accidentally exposed.

For production automation, prefer a secrets-management system that materializes the file only for the job that needs it.

In short: Use --config proxy.conf for deliberate, reusable proxy settings. Protect the file and never commit it to Git.

How Do You Bypass a cURL Proxy for Selected Domains?

Use --noproxy to connect directly to selected hosts even when a proxy is configured. This is useful for localhost, internal services, and destinations that should not traverse the proxy.

The value is a comma-separated list. It can contain exact hostnames, domain patterns, IP addresses, and supported CIDR networks:

--noproxy replaces the exclusions supplied by NO_PROXY or no_proxy for that command.

This also means an unexpected NO_PROXY value can make a request connect directly even when --proxy is present. Check both the command and the environment when cURL appears to ignore a proxy.

In short: Use NO_PROXY for shell- or job-wide exclusions and --noproxy for command-specific exclusions.

How Do You Verify That cURL Is Using the Proxy?

Verify a cURL proxy by comparing the public exit IP with and without the proxy, then inspect the connection with --verbose if the result is unclear or the request fails.

Step 1: Check the Direct IP

Step 2: Check the Proxied IP

The proxied request should return the proxy’s exit IP rather than the original public IP. A rotating proxy may return a different exit IP on later requests.

For a broader quality check, the proxy testing guide explains how to evaluate anonymity, reputation, speed, latency, and uptime.

Step 3: Inspect the Connection

For an HTTP proxy carrying an HTTPS destination, look for:

• A connection to the proxy hostname or IP.
• A CONNECT example.com:443 request.
• A successful 200 Connection established response from the proxy.
• A 407 Proxy Authentication Required response if authentication failed.
• TLS certificate validation messages for the proxy or destination.
• The final response from the destination.

On cURL 8.7.0 and newer, %{proxy_used} can provide a script-friendly check:

proxy_used=1 means the transfer used a proxy.

For a proxied connection, remote_ip normally reports the proxy endpoint cURL connected to, not necessarily the final exit IP seen by the website. Use the IP-check request to verify the exit address.

Verbose and trace output can contain credentials, authorization headers, cookies, or request data. Redact it before sharing or attaching it to a support ticket.

In short: An exit-IP comparison verifies the result, while --verbose shows how cURL reached it. Use both when diagnosing a proxy configuration.

How Do You Add Timeouts and Safer Defaults to a cURL Proxy Command?

Set both a connection timeout and a total transfer timeout so a dead proxy cannot leave a job hanging indefinitely. For read-only GET requests, limited retries can handle transient failures.

Use retries carefully. A GET or HEAD request is normally safe to repeat, but a POST, purchase, upload, or other state-changing request may have side effects.

Only retry those operations when the destination API defines them as idempotent or uses an idempotency key.

For a minimal timeout-only command:

In short: --connect-timeout limits setup time, while --max-time limits the full transfer attempt. Use both in unattended jobs.

What Are the Most Common cURL Proxy Errors?

Most cURL proxy failures come from an incorrect endpoint, blocked port, authentication mismatch, DNS behavior, certificate trust problem, or timeout.

Start with the exact cURL error, then use --verbose to locate the failed stage.

If credentials are embedded in a proxy URL, cURL URL-decodes them.

For example:

• Encode @ as %40.
• Encode a literal colon as %3A.

Using a separately quoted --proxy-user value is usually clearer, but it still does not turn the command line into secure secret storage.

Use this diagnostic order:

1. Run curl --version to confirm the executable and supported features.
2. Request the destination without a proxy to separate target failures from proxy failures.
3. Request an IP-check endpoint through the proxy.
4. Add --verbose and identify whether the failure occurs at DNS, TCP, proxy authentication, CONNECT, proxy TLS, destination TLS, or the final HTTP response.
5. Confirm the proxy scheme, hostname, port, credentials, and authentication method.
6. For SOCKS5, confirm whether local or proxy-side destination DNS is required.
7. Add explicit timeouts and test again.

For related diagnostics, see:

• How to resolve proxy error codes
• How to fix error code 407
• How to test proxies
• How to handle cURL SSL certificate errors

In short: Use the error message to identify the failed layer. Then verify the endpoint, authentication, DNS mode, certificates, and timeouts in that order.

How Should You Protect Proxy Credentials in cURL?

Keep proxy credentials out of source code and shared command history. Use a protected config file or secrets-management system, limit who can read it, and redact diagnostic output before sharing it.

Using --proxy-user is preferable to embedding credentials in the proxy URL because it keeps them out of copied URLs and ordinary URL logs. However, a literal password may still be briefly visible in shell history or process information.

The official cURL manual warns that cURL’s attempt to hide a command-line credential is not sufficient because another user may see it before it is cleared. The manual recommends retrieving sensitive data from a file or similar protected source.

Follow these practices:

• Store production credentials in a secret manager or protected cURL config file.
• Give credential files restrictive permissions and keep them out of Git.
• Do not paste secrets into tickets, chat messages, documentation, or screenshots.
• Quote command-line credentials to reduce shell interpretation problems.
• Redact Proxy-Authorization, cookies, tokens, usernames, and passwords from verbose logs.
• Use HTTPS destinations for sensitive data.
• Use an HTTPS proxy when the cURL-to-proxy hop also needs TLS protection.
• Rotate exposed or leaked credentials immediately.
• Give each credential only the permissions and lifetime it needs.

Environment variables can reduce accidental hardcoding, but they are not automatically secret. They may appear in CI output, crash reports, child-process environments, or system diagnostics.

Treat environment variables as a delivery mechanism for a secret, not as the protection boundary itself.

In short: --proxy-user improves command clarity, not password secrecy. Protected files and secrets managers are the safer choices for automation.

Should You Use an HTTP or SOCKS5 Proxy With cURL?

Use an HTTP proxy for most websites, APIs, and web scraping requests. Use SOCKS5 when the client needs a more general TCP relay or when the destination hostname should be resolved from the proxy network.

Neither HTTP nor SOCKS5 automatically encrypts the application payload. HTTPS protects an HTTPS destination, while an HTTPS proxy protects the client-to-proxy hop.

Choose the protocol your software and proxy provider support, then test it against the real target.

In short: Start with HTTP for web traffic. Choose socks5h:// when SOCKS5 flexibility or proxy-side destination DNS is a requirement.

Conclusion

Using cURL with a proxy requires the correct endpoint scheme, authentication option, DNS behavior, and verification method. Most setups work with --proxy and --proxy-user; the remaining flags control transport security, exclusions, reliability, and debugging.

The key takeaways are:

• Use --proxy or -x to set an HTTP, HTTPS, or SOCKS proxy.
• Use --proxy-user or -U for both HTTP-family and SOCKS5 proxy credentials.
• Replace the invalid --socks5-user and --socks5-password flags with --proxy-user.
• Use socks5h:// or --socks5-hostname for proxy-side destination DNS.
• Remember that an HTTP proxy can carry an HTTPS destination through CONNECT.
• Use an https:// proxy URL only when the cURL-to-proxy connection itself uses TLS.
• Prefer --proxy-cacert over --proxy-insecure for a private proxy CA.
• Use environment variables for shared configuration and NO_PROXY or --noproxy for exceptions.
• Compare exit IPs and use --verbose to verify the connection path.
• Add connection and transfer timeouts to unattended commands.
• Keep proxy credentials in protected configuration files or secrets-management systems.

Start with the quick-start command that matches your proxy protocol, replace the placeholders with the endpoint details from your provider, and verify the exit IP before adding the command to a script or production job.