Introduction

The JVM can use proxies through standard system properties, command-line flags, or programmatic proxy selection. The right approach depends on whether you want one global proxy for the whole process or fine-grained control per request or per protocol.

Use JVM System Properties For Global Proxy Settings

The most common way is to set system properties for HTTP and HTTPS:

1System.setProperty("http.proxyHost", "proxy.example.com");
2System.setProperty("http.proxyPort", "8080");
3System.setProperty("https.proxyHost", "proxy.example.com");
4System.setProperty("https.proxyPort", "8080");
5System.setProperty("http.nonProxyHosts", "localhost|127.0.0.1|*.internal");

This affects code that respects the standard JVM networking properties.

A large part of older Java networking code and many libraries pick up these values automatically, which is why they remain the default answer.

The Same Settings Can Be Passed At Startup

Instead of setting them in code, you can supply them on the command line:

1java \
2  -Dhttp.proxyHost=proxy.example.com \
3  -Dhttp.proxyPort=8080 \
4  -Dhttps.proxyHost=proxy.example.com \
5  -Dhttps.proxyPort=8080 \
6  -Dhttp.nonProxyHosts="localhost|127.0.0.1|*.internal" \
7  -jar app.jar

This is often cleaner in production because proxy configuration stays outside the application code.

It also makes environment-specific changes easier across local development, CI, and deployment systems.

Use Authentication If The Proxy Requires It

If the proxy needs credentials, add an Authenticator:

1import java.net.Authenticator;
2import java.net.PasswordAuthentication;
3
4Authenticator.setDefault(new Authenticator() {
5    @Override
6    protected PasswordAuthentication getPasswordAuthentication() {
7        return new PasswordAuthentication(
8            "proxy-user",
9            "proxy-password".toCharArray()
10        );
11    }
12});

This works with Java networking APIs that participate in the standard authentication flow.

Per-Request Proxy Control Is Different

Sometimes a global JVM proxy is too blunt. In that case, use a proxy object on the client API itself:

1import java.io.BufferedReader;
2import java.io.InputStreamReader;
3import java.net.InetSocketAddress;
4import java.net.Proxy;
5import java.net.URL;
6
7Proxy proxy = new Proxy(
8    Proxy.Type.HTTP,
9    new InetSocketAddress("proxy.example.com", 8080)
10);
11
12URL url = new URL("http://example.com");
13try (var connection = url.openConnection(proxy);
14     var reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
15    System.out.println(reader.readLine());
16}

This is useful when different outbound calls should use different routes or when only part of the application should go through the proxy.

System Proxies And Non-Proxy Hosts

The JVM can also be told to consult operating-system proxy settings:

System.setProperty("java.net.useSystemProxies", "true");

That can be convenient on managed desktops, but it makes behavior depend more heavily on the host environment. If you need deterministic deployment behavior, explicit JVM properties are often clearer.

Non-proxy hosts matter too. Without them, internal calls to localhost, loopback, or private domains may get routed unnecessarily through the proxy.

That becomes especially important in enterprise environments where health checks, callbacks, and internal service calls should stay on private routes instead of being pushed through a corporate proxy by accident.

When troubleshooting, print the effective system properties at startup so you know which proxy settings the process actually received. That simple check prevents a lot of confusion between code defaults, shell flags, and deployment-time overrides.

Common Pitfalls

One common mistake is setting only the HTTP proxy and forgetting HTTPS, then wondering why secure connections still bypass the proxy or fail.

Another issue is assuming every third-party library honors the JVM's standard proxy properties automatically. Many do, but not all.

A third problem is hard-coding proxy credentials in application source instead of using environment or deployment configuration.

Finally, developers sometimes use global JVM proxy settings when only one client or one service call actually needs a proxy, which makes debugging routing behavior harder.

Summary

• Use http.proxyHost, http.proxyPort, https.proxyHost, and https.proxyPort for standard JVM-wide proxy configuration.
• Passing these as -D flags at startup is often cleaner than setting them in code.
• Add http.nonProxyHosts to keep local or internal traffic out of the proxy.
• Use an Authenticator if proxy authentication is required.
• For fine-grained routing, create per-request proxy settings instead of changing the whole JVM.