The proxy plugin allows one to send HTTP requests through a proxy.

All examples will assume the fictitious address/port pair. Replace the examples with your own.


After enabling the plugin, you can call a #proxy method, which can receive the following options:

  • :uri: the proxy URI (see examples below)
  • :username: proxy user (optional)
  • :password: proxy password (optional)
  • :no_proxy: list of domains/patterns that bypass the proxy (optional)
# Use an HTTP cache proxy to route clear-text HTTP requests:
HTTPX.plugin(:proxy).with_proxy(uri: "").get("")
# Use an HTTPS `CONNECT` proxy to tunnel secure HTTP(S) requests.
HTTPX.plugin(:proxy).with_proxy(uri: "").get("")
# Use a SOCKS proxy
HTTPX.plugin(:proxy).with_proxy(uri: "socks4://").get("")
HTTPX.plugin(:proxy).with_proxy(uri: "socks4a://").get("")
HTTPX.plugin(:proxy).with_proxy(uri: "socks45://").get("")

# no proxy
HTTPX.plugin(:proxy).with_proxy(uri: "", no_proxy: ["", /*]).get("")


httpx supports proxy authentication for all the supported HTTP authentication schemes:

# will do basic auth by default
HTTPX.plugin(:proxy).with_proxy(uri: "", username: "user", password: "password").get("")
# can also explicitly call basic auth
HTTPX.plugin(:proxy).with_proxy_basic_auth(uri: "", username: "user", password: "password").get("")
# proxy digest auth (since v0.20)
HTTPX.plugin(:proxy).with_proxy_digest_auth(uri: "", username: "user", password: "password").get("")
# proxy ntlm auth (since v0.20)
HTTPX.plugin(:proxy).with_proxy_ntlm_auth(uri: "", username: "user", password: "password").get("")


This plugin creates an SSH connection (using the net-ssh-gateway gem) and tunnels all requests from the session through it.

session = HTTPX.plugin(:"proxy/ssh")
               .with_proxy(uri: "ssh://",
                           username: "root",
                           password: "root")
response = session.get("")

ENV http_proxy/https_proxy/no_proxy

If the proxy environment variables are defined, HTTPX will load with the plugin turned on by default. It will therefore route or not route the requests through a proxy based on those variables. Their declaration format is the same as the one used in the proxy :uri parameter.


Because of the implicit sharing of known peer IP, HTTP/2 connection coalescing is disabled. HTTP/1.1 pipelining support may also be limited (most proxies don’t support it), so beware of its utilization.

Next: Authentication