Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Create the connection with Faraday.new and pass a proxy option. Use a URL for a proxy without authentication, or a hash containing uri, user, and password. If you omit the option, Faraday attempts to discover a proxy from the environment. The adapter installed in your application performs the actual network request, so verify proxy and authentication behavior against that adapter and your Faraday version.
Configure an explicit proxy on one Faraday connection
An explicit proxy is the most predictable choice when a particular client must always use a particular route. The setting belongs in the options passed to Faraday.new, alongside the base URL and any other connection configuration.
Authenticated proxy
This complete example keeps credentials outside the source file. ENV.fetch(name, nil) returns nil when a credential is not supplied, which also lets the same configuration work with an unauthenticated proxy.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →require 'faraday'
connection = Faraday.new(
url: 'https://api.example.com',
proxy: {
uri: 'http://proxy.example.com:8080',
user: ENV.fetch('PROXY_USER', nil),
password: ENV.fetch('PROXY_PASSWORD', nil)
}
)
response = connection.get('/status')
puts response.status
puts response.bodyThe proxy hash uses uri for the proxy address and optional user and password values for authentication. Do not commit real credentials to a repository. Supply them through your deployment secret manager or process environment, and ensure logs do not print the resulting configuration.
#1 Best Overall
Unauthenticated proxy
For a proxy that does not require credentials, the shorter URL form is sufficient:
require 'faraday'
connection = Faraday.new(
url: 'https://api.example.com',
proxy: 'http://proxy.example.com:8080'
)
response = connection.get('/status')Both forms are connection-specific. Two Faraday connections in the same Ruby process can therefore use different proxies by receiving different proxy options.
What Faraday does when you do not set proxy
With no manual proxy option, Faraday’s connection implementation attempts environment-based discovery. For a URL with a host it uses Ruby’s URI#find_proxy; its default-proxy path checks the lowercase http_proxy variable. This means a deployment, shell, container, or CI runner can silently change the route used by an otherwise unchanged Ruby program.
Recommended Free Tools
Environment variables and scope
Set the environment before starting the Ruby process. A typical shell setup is:
export http_proxy=http://proxy.example.com:8080
export PROXY_USER=build-user
export PROXY_PASSWORD='use-your-secret-store'Do not assume that uppercase and lowercase spellings, or no_proxy exclusions, behave identically in every Faraday and Ruby version. The exact environment handling is version-sensitive, so inspect the Faraday version deployed with the application and test the variables that your runtime actually sets.
Disable environment discovery deliberately
Faraday exposes the global ignore_env_proxy setting. Versioned API documentation for Faraday 2.14.3 says its default is false, so environment lookup is enabled unless you change it.
Rank #2
- Used Book in Good Condition
require 'faraday'
Faraday.ignore_env_proxy = true
connection = Faraday.new(url: 'https://api.example.com')
response = connection.get('/status')This is a process-wide setting, not a property of only the connection created on the next line. In a shared application, changing it can affect other clients and libraries that create Faraday connections. Prefer an explicit per-connection proxy when only one client needs a special route; use the global switch only when you control the implications for the whole process.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsExplicit proxy versus environment-derived proxy
| Choice | How it is selected | Best fit | Main consideration |
|---|---|---|---|
Explicit proxy option |
URL or hash passed to Faraday.new |
A client that must have a visible, deterministic route | Configuration is present in application code or injected settings and must be maintained there |
| Environment discovery | Faraday consults the runtime environment when no manual proxy is supplied | Deployments that centrally provide network configuration | The route can change outside the code, and variable-name or exclusion behavior is version-sensitive |
There is no universal winner. Explicit configuration makes the connection's intent easy to review. Environment discovery is useful when the same artifact runs in several networks and operations owns the proxy setting. Whichever model you choose, record it in deployment documentation and test it in the environment where the application will run.
Adapters determine the network behavior
Faraday does not make HTTP requests itself; it delegates request execution to a Faraday adapter. The quick-start documentation identifies Net::HTTP, which is part of Ruby's standard library, as the default adapter. Other adapters are available separately.
Consequently, a proxy declaration that parses correctly at the Faraday connection layer is not a guarantee that every adapter handles routing, proxy authentication, TLS, timeouts, or errors in exactly the same way. Check the documentation for the adapter installed in your bundle and exercise the configuration with that adapter, not only with a local default.
Identify the adapter in the application
Look at the Faraday.new block and your bundle configuration. If the block contains an adapter selection, that is the implementation to investigate. If it does not, confirm the default for the Faraday version and dependencies actually installed in the deployment. A lockfile review is useful because a developer machine and production machine can otherwise resolve different adapter versions.
Test the path with a small request
Use a harmless endpoint and print only status and timing information. Avoid logging authorization headers, proxy passwords, cookies, or full response bodies when they could contain sensitive data.
require 'faraday'
connection = Faraday.new(
url: 'https://api.example.com',
proxy: 'http://proxy.example.com:8080'
)
begin
response = connection.get('/status')
puts "HTTP #{response.status}"
rescue Faraday::Error => e
warn "Faraday request failed: #{e.class}: #{e.message}"
raise
endThis confirms that the request can be issued through the configured stack, but it does not prove that every URL, method, response size, or authentication flow will behave identically. Test the real request pattern before deploying it.
Credentials, URLs, and safe configuration
Keep secrets out of source and logs
Use environment injection or your platform's secret manager for proxy usernames and passwords. Avoid putting a credential-bearing URL in a command line that other users can inspect, and redact proxy settings in diagnostic output. If a password contains characters that have special meaning in a URL, the hash form avoids URL-encoding mistakes because the credential is passed as a separate value.
Use separate connections for separate trust boundaries
If one upstream must use a corporate proxy and another must connect directly, create two Faraday connections with explicit settings rather than changing a global process setting between requests. This keeps routing attached to the client that needs it and avoids race-prone configuration changes.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchChoose the proxy scheme deliberately
The examples use an HTTP proxy URI with a host and port. Whether a different scheme, authentication method, or TLS arrangement is supported depends on the adapter and proxy service. Confirm accepted schemes and credential handling in the adapter documentation before promoting a change.
Troubleshooting common failures
The request unexpectedly uses a proxy
Likely cause: no explicit proxy option was supplied and the process environment contains http_proxy or related settings.
Fix: inspect the environment inherited by the Ruby process. If this connection must be direct, set Faraday.ignore_env_proxy = true only after considering its process-wide effect, or provide the intended explicit connection configuration and remove the unwanted deployment variable.
The request bypasses the proxy you expected
Likely cause: the environment variable spelling, URL host, or exclusion rules are not being interpreted as you assumed, or a manual option overrides the environment.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix: print a redacted description of the selected configuration, verify the exact Faraday version, and test lowercase http_proxy because that is the documented default-proxy path. Treat uppercase variables and no_proxy behavior as version-sensitive rather than guaranteed.
The proxy returns an authentication error
Likely cause: missing or incorrect credentials, a credential that has expired, or authentication behavior that differs in the selected adapter.
Fix: verify user and password values from the secret source, ensure they are not accidentally empty strings, and consult the adapter's proxy-authentication documentation. Never solve the problem by committing a password to the repository.
The proxy option raises an argument or parsing error
Likely cause: the application is running a different Faraday version than the example targets, or a value was supplied under the wrong key.
Fix: check the installed gem version and use the documented URL or hash shape: proxy: 'http://host:port' or proxy: { uri: 'http://host:port', user: ..., password: ... }. Then verify that the adapter selected by the application accepts the resulting configuration.
Best Value
The connection times out only in deployment
Likely cause: the deployment network cannot reach the proxy host or the proxy cannot reach the target, even though the developer machine can.
Fix: test DNS and outbound connectivity from the actual runtime environment, confirm the proxy host and port supplied there, and compare the deployed adapter and Faraday versions with local versions. A successful local request does not establish that the production network path is available.
Changing ignore_env_proxy breaks another client
Likely cause: the setting is global and another component creates Faraday connections in the same process.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Fix: remove the global mutation where possible and configure the required proxy explicitly on the connection that needs it. If a global policy is unavoidable, document it and test all Faraday clients in the process.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Operational checklist
- Confirm the Faraday gem version and the adapter selected by the application.
- Choose explicit per-connection configuration or environment discovery and document that choice.
- Use the documented
uri,user, andpasswordkeys for an authenticated proxy. - Inject credentials through a secret mechanism and redact them from logs.
- Check lowercase
http_proxyand treat uppercase variables andno_proxybehavior as version-sensitive. - Use a small, safe request to validate the route from the real deployment network.
- Do not change the global environment-proxy switch without checking every Faraday client in the process.
Or skip the browser setup
If your Ruby workflow also needs a rendered screenshot of a URL for documentation, QA, or an automated report, ScreenshotNeo provides a website screenshot API and MCP server. It is separate from Faraday's proxy configuration: call its endpoint when you need an image or PDF rather than wiring a browser into your Ruby process.
One GET request returns the capture. The API documentation is at https://screenshotneo.com/docs/.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts the cookie or consent banner before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the result through X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to start.
Bottom line
For a stable, reviewable route, pass proxy directly to Faraday.new and keep credentials outside source code. Let Faraday discover an environment proxy only when deployment-managed routing is intentional. Because the adapter performs the request, verify the exact adapter and Faraday version before relying on proxy authentication or environment edge cases.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
