skip to content

How do you configure <proxies>, <localRepository>, and <offline> in settings.xml, and when does each matter?

level: middleimportance: should knowfreq 45%

answer

  1. <proxies> = network/firewall proxy, needs <active>true
  2. nonProxyHosts = bypass list (| separated)
  3. <localRepository> default ~/.m2/repository (-Dmaven.repo.local)
  4. <offline>true == mvn -o, cache only
  5. proxy != mirror

basics

~10 s

<proxies> sets an HTTP/HTTPS network proxy (with optional nonProxyHosts). <localRepository> changes where downloaded artifacts are cached (default ~/.m2/repository). <offline>true</offline> makes Maven build only from the local cache, never hitting the network.

solid answer

~40 s

These three settings.xml elements control network and caching behavior. `<proxies>` defines an outbound **network proxy** (protocol, host, port, optional username/password and `<nonProxyHosts>` for direct-connect exceptions) — needed behind a corporate firewall; only `<active>true</active>` proxies apply and the first active one per protocol is used. `<localRepository>` overrides the default artifact cache (`~/.m2/repository`), e.g. to put it on faster disk or share between users. `<offline>true</offline>` puts Maven in offline mode (same as `mvn -o`): it resolves everything from the local repo and never contacts remote repositories — useful for reproducible/air-gapped builds, but it fails if a required artifact isn't already cached. Note `<proxies>` is a *network* proxy (firewall traversal), distinct from a `<mirror>`, which is a *repository* redirect.

code

xml · 10 lines
xml
<proxies>
  <proxy>
    <id>corp</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>proxy.example.com</host>
    <port>8080</port>
    <nonProxyHosts>localhost|*.internal.example.com</nonProxyHosts>
  </proxy>
</proxies>

go deeper

for a junior

Knows the local repo defaults to ~/.m2/repository and offline avoids the network.

for a middle

Configures a proxy with nonProxyHosts, relocates the local repo, and knows offline == -o.

for a senior

Distinguishes proxy vs mirror, warms caches for offline/air-gapped builds, isolates CI caches.

for a principal

Standardizes proxy/cache strategy across teams and CI; designs reproducible/air-gapped build infra.

## <proxies> — network/HTTP proxy When your machine reaches the internet only through a corporate proxy, configure it here so Maven can download artifacts: ```xml <proxies> <proxy> <id>corp-proxy</id> <active>true</active> <protocol>https</protocol> <host>proxy.example.com</host> <port>8080</port> <username>me</username> <password>secret</password> <nonProxyHosts>localhost|*.internal.example.com</nonProxyHosts> </proxy> </proxies> ``` - `<active>` must be `true` for the proxy to apply. - `<protocol>` is typically `http`/`https`. - `<nonProxyHosts>` is a `|`-separated list of hosts to reach **directly**, bypassing the proxy (e.g. internal Nexus). - Only one active proxy per protocol is used (first wins). This is a **network** proxy — it does not redirect which repository is used. That's a `<mirror>`'s job. They are often used together: a mirror points at internal Nexus, and a proxy lets Maven reach external hosts. ## <localRepository> — the artifact cache Maven caches every downloaded artifact (and your installed modules) in the **local repository**, default `${user.home}/.m2/repository`. Override it: ```xml <localRepository>/data/maven-cache</localRepository> ``` Reasons to change it: put the cache on a faster/larger disk, isolate per-job caches on CI, or relocate off the home directory. You can also override per-build with `mvn -Dmaven.repo.local=/path`. ## <offline> — work without the network ```xml <offline>true</offline> ``` Equivalent to `mvn -o`. Maven resolves dependencies and plugins **only** from the local repository and never contacts remote repos. Benefits: deterministic builds, no network dependency, faster startup. Risk: the build **fails** the moment something needed isn't already cached (so you typically warm the cache online first, e.g. `mvn dependency:go-offline`). ## How they interact When `<offline>` is true, `<proxies>` and `<mirrors>` are irrelevant because nothing goes over the network. Otherwise, a request flows: pick repository (possibly redirected by a mirror) -> reach it via the network proxy if configured -> cache the result in the local repository.

  • What's the difference between a <proxy> and a <mirror>?
    A <proxy> is a network/HTTP proxy for traversing a firewall; a <mirror> redirects which repository URL Maven uses. They solve different problems and are often combined.
  • A build with <offline>true</offline> fails resolving a new dependency. Why?
    Offline mode never contacts remote repos, so any artifact not already in the local repository cannot be downloaded and resolution fails. Warm the cache online first (e.g. dependency:go-offline).

saying these in an interview costs you the question

  • Conflating <proxies> (network proxy) with <mirrors> (repo redirect).
  • Forgetting <active>true</active> so the proxy is silently ignored.
  • Thinking offline mode will still download missing artifacts.

context

resolving links…