Edit

Proxy

By default, coursier relies on java.net.HttpURLConnection to handle HTTP requests. java.net.HttpURLConnection automatically picks up proxy related properties.

Properties

The following Java system properties control proxy behaviour:

Property	Description
https.proxyHost	Hostname of the proxy for HTTPS connections
https.proxyPort	Port of the proxy for HTTPS connections (default: 443)
https.proxyUser	Username for proxy authentication (HTTPS)
https.proxyPassword	Password for proxy authentication (HTTPS)
http.proxyHost	Hostname of the proxy for HTTP connections
http.proxyPort	Port of the proxy for HTTP connections (default: 80)
http.proxyUser	Username for proxy authentication (HTTP)
http.proxyPassword	Password for proxy authentication (HTTP)
http.nonProxyHosts	Pipe-separated list of host patterns that bypass the proxy (e.g. `localhost\	*.internal.example.com`)

Basic authentication for HTTPS proxy tunnels

Since 8u111, the JDK refuses to send Basic credentials when tunneling HTTPS connections through a proxy (Basic is listed in the jdk.http.auth.tunneling.disabledSchemes property, in $JAVA_HOME/conf/net.properties).

When proxy credentials are configured (via the http.proxyUser / https.proxyUser properties, the <username> of a proxy in Maven settings.xml, or the proxy user of the Scala CLI configuration), coursier removes Basic from the jdk.http.auth.tunneling.disabledSchemes property, so that authenticated proxies work. This setting applies to the whole JVM. coursier leaves the property alone when no proxy credentials are configured, or when the property was already set, like with

$ java -Djdk.http.auth.tunneling.disabledSchemes=Basic …

which keeps Basic authentication disabled for proxy tunnels.

Maven settings.xml

Coursier automatically reads proxy settings from the Maven settings.xml file. It looks for settings.xml in the following locations, in order:

1. The directory given by the CS_MAVEN_HOME environment variable
2. The directory given by the MAVEN_HOME environment variable
3. The directory given by the cs.maven.home Java property
4. The directory given by the maven.home Java property
5. ~/.m2 (the Maven default)

If the file is found, coursier reads any <proxy> entries whose <active> element is true (or absent) and configures the corresponding Java system properties automatically.

Example ~/.m2/settings.xml:

<settings>
  <proxies>
    <proxy>
      <id>my-proxy</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>proxy.example.com</host>
      <port>3128</port>
      <username>proxyuser</username>
      <password>proxypass</password>
      <nonProxyHosts>localhost|*.internal.example.com</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

The <protocol> element specifies whether the proxy itself communicates over HTTP or HTTPS (it does not filter which target URLs go through the proxy). If <protocol> is omitted, https is assumed.

CLI

To set proxy properties directly, run the CLI with -D flags:

$ java -Dhttps.proxyHost=… -Dhttps.proxyPort=… \
     -jar $(which coursier) [args]

instead of coursier [args]. Alternatively, recent versions of coursier should accept those options prefixed with -J, like

$ coursier -J-Dhttps.proxyHost=… -J-Dhttps.proxyPort=… [args]

sbt

Set those properties when starting sbt, like

$ sbt -Dhttps.proxyHost=… -Dhttps.proxyPort=… [args]

Alternatively, pass those by setting JAVA_OPTS in the environment.

API

Ensure the right Java properties are set when running your application, either from the command line when running your application, via

$ java -Dhttps.proxyHost=… -Dhttps.proxyPort=… [args]

or by setting them yourself before anything coursier is run, like

System.setProperty("https.proxyHost", "…")
System.setProperty("https.proxyPort", "…")

If you want coursier to read proxy settings from ~/.m2/settings.xml automatically (the same way the CLI does), call SetupProxy.setup() early in your application:

import coursier.proxy.SetupProxy;

SetupProxy.setup(); // reads ~/.m2/settings.xml and registers a proxy Authenticator

SetupProxy.setup() both configures the proxy system properties (https.proxyHost, etc.) from the Maven settings file and registers a java.net.Authenticator so that authenticated proxies work correctly. If proxy credentials are configured, it also enables Basic authentication for HTTPS proxy tunnels, see above.