Routing WordPress Outbound Requests Through a Proxy with wp-config.php
By the ProxyV4 Engineering Team · Updated:
WordPress proxy settings live in wp-config.php as five constants, WP_PROXY_HOST, WP_PROXY_PORT, WP_PROXY_USERNAME, WP_PROXY_PASSWORD and WP_PROXY_BYPASS_HOSTS, and they route every request made through the WordPress HTTP API via one outbound proxy. That covers core updates, plugin and theme installs, and any plugin that calls wp_remote_get() or wp_remote_post(). It does not cover plugins that open their own cURL handles, which is the part most guides skip.
When a WordPress outbound proxy makes sense
Most sites never need one. The constants exist for three situations: a server on a locked-down network where direct internet access is blocked and every outbound connection must go through a corporate gateway; an external API (a payment processor, a shipping carrier, a CRM) that only accepts calls from a short list of approved source IPs while your host changes addresses or shares them; and a need to make outbound calls from a specific country, such as a pricing feed that answers differently by region.
In all three, the goal is the same: WordPress talks to the outside world from one address you control. Inbound visitors are unaffected. The proxy only sees requests your site makes, never requests made to it.
The five constants and what each one does
WordPress reads these through its WP_HTTP_Proxy class. All of them are optional except the host and port, and the class only switches on when both of those are defined.
| Constant | Example value | Effect |
|---|---|---|
WP_PROXY_HOST | '203.0.113.25' | Proxy address; without it, nothing is proxied |
WP_PROXY_PORT | '8080' | Proxy port; required together with the host |
WP_PROXY_USERNAME | 'USER' | Sent as Basic proxy authentication |
WP_PROXY_PASSWORD | 'PASS' | Paired with the username |
WP_PROXY_BYPASS_HOSTS | 'localhost, *.wordpress.org' | Comma-separated hosts that go direct; * wildcards are accepted in recent versions |
Hosts that never go through the proxy
Even without a bypass list, WordPress sends requests for localhost and for your own site's hostname directly. That keeps WP-Cron and loopback checks working. Anything you add to WP_PROXY_BYPASS_HOSTS joins that list, which is useful for internal services on the same private network.
Only HTTP proxies are understood
The HTTP API speaks to the proxy as an HTTP proxy and tunnels https:// destinations with CONNECT. There is no SOCKS5 option in these constants. If your provider lets you choose the mode, set the line to HTTP (or HTTP and SOCKS5 on the same port) before you paste it in.
Where WordPress proxy settings go in wp-config
Open wp-config.php in the site root and add the block above the line that reads /* That's all, stop editing! Happy publishing. */. Constants defined after wp-settings.php is loaded arrive too late for some early requests, so placement matters.
/* Outbound proxy for the WordPress HTTP API */
define( 'WP_PROXY_HOST', 'IP' );
define( 'WP_PROXY_PORT', 'PORT' );
define( 'WP_PROXY_USERNAME', 'USER' );
define( 'WP_PROXY_PASSWORD', 'PASS' );
define( 'WP_PROXY_BYPASS_HOSTS', 'localhost, 127.0.0.1, *.internal.example' );If your proxy comes as one line in the form ip:port:user:pass, the four fields map to the first four constants in that order. The proxy format converter splits a line for you if you have a batch to deal with. Keep quotes around every value, and avoid putting the password in version control: on managed hosts that support environment variables, define( 'WP_PROXY_PASSWORD', getenv( 'WP_PROXY_PASSWORD' ) ); keeps it out of the file.
Test that wp_remote_get really leaves through the proxy
Do not judge success by whether updates still work; they also work without the proxy. Ask an external service which IP it sees. With WP-CLI on the server:
wp eval 'echo wp_remote_retrieve_body( wp_remote_get( "https://proxyv4.com/api/my-ip" ) ), "\n";'The address printed should be the proxy IP, not the server's own. If you have no shell access, drop the same call into a small must-use plugin temporarily, or compare the result of the my IP tool opened from the server with what the external API reports in its logs.
Then open Tools > Site Health. The checks for reaching WordPress.org and for background updates use the same HTTP API, so a failure there right after you add the constants points at the proxy settings rather than the site.
Fixing WordPress behind proxy update errors
When the constants are wrong, the symptom is usually a cURL error string inside a WordPress message, such as an update screen saying it could not establish a secure connection. The cURL number in the message tells you which hop failed.
cURL error 7 or 28: the proxy is not reachable
Error 7 usually means the TCP connection to the proxy was refused; 28 means it timed out. If the message also contains CONNECT tunnel failed, skip to the next heading. Check from the server itself, not your laptop, because hosting firewalls often block unusual outbound ports: curl -v -x http://IP:PORT -U USER:PASS https://wordpress.org. If that hangs too, ask your host to allow outbound traffic to that port, or test the port with the port checker.
A 407 in the error: the login is wrong
A CONNECT tunnel failed, response 407 (cURL error 56, or 7 with very recent libcurl builds) means the proxy answered and rejected the credentials. Look for stray spaces copied into the constants and for a password containing a single quote, which ends the PHP string early. The 407 guide lists the other usual suspects.
Everything works except one plugin
That plugin almost certainly calls curl_init() directly or ships its own HTTP client such as Guzzle. Those bypass WP_HTTP_Proxy entirely. Some expose their own proxy setting; otherwise the plugin author has to switch to wp_remote_request(), or you set proxy options inside the client it uses. Payment SDKs are the usual example, which matters if the reason you added a proxy was a gateway that checks your source IP.
Picking an IP for an outbound WordPress proxy
For this job you want an address that never changes and that nobody else sends traffic from, because the external service will remember it. A rotating pool is the wrong tool: the next request leaves from a different IP and the API rejects it. A private datacenter IPv4 from ProxyV4 fits well. It is one tenant per IP for the whole term, it keeps the same address as long as you renew before expiry, and the order line works in these constants as an HTTP proxy with username and password. You can buy a single IP; WordPress needs only one.
It is not the right fit if the API you call only accepts IPv6 sources, because this product is IPv4 (IPv6 proxies are sold separately), or if you need many changing exit IPs. Traffic on private IPv4 is not metered, so plugin update downloads do not add cost. Pick the country that the external service expects, check the live per-IP prices on the pricing page, and test the line with the WP-CLI command above before you register it with the API.
Security notes before you go live
- Anyone who can read
wp-config.phpcan read the proxy password. Keep the file permissions tight (for example640or600, depending on how your host runs PHP). - Do not proxy calls to your own database or object cache; they do not use the HTTP API anyway, and bypassing internal hostnames avoids surprises.
- If a plugin offers a filter,
pre_http_send_through_proxylets code decide per URL whether to use the proxy, which is cleaner than a long bypass list. - Record the proxy IP and its renewal date next to the API key that depends on it. An expired proxy looks exactly like an API outage.
Frequently asked questions
Does WP_PROXY_HOST affect visitors to my site?
No. It only applies to requests WordPress sends out through its HTTP API. Visitors still reach your server directly.
Can I use a SOCKS5 proxy in wp-config.php?
Not with the built-in constants, which treat the proxy as HTTP. A provider line that supports both HTTP and SOCKS5 on the same port works fine when you use it as HTTP.
Why does WooCommerce still call the payment API from my server IP?
The gateway extension probably uses its own HTTP client rather than wp_remote_post. Check its settings for a proxy field or ask its developer, because the WordPress constants cannot reach it.
Will the outbound IP change when I renew the proxy?
With ProxyV4, renewing before expiry keeps the same address, so an API that recognizes your IP keeps accepting it. Letting the proxy lapse can cost you that address.
Does WP-CLI respect the WordPress proxy constants?
Commands that run WordPress code, such as wp eval or plugin updates through core, use the HTTP API and therefore the constants. Behavior of other WP-CLI commands varies by version, so test the one you depend on.
Give WordPress one fixed outbound IP
A private IPv4 from ProxyV4 keeps the same address while it stays active and works as an HTTP proxy with username and password in wp-config.php. Order a single IP, confirm it with wp_remote_get, then register it with your API.
Try one private IP