How to Set Maven’s Local Repository Location (And Why It Doesn’t Belong in pom.xml)

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

You can’t set Maven’s local repository location with a standard element in pom.xml. Configure it in settings.xml, pass it to a Maven command with -Dmaven.repo.local, or use a project-level Maven configuration file where supported. Maven’s local repository is a user- or machine-specific cache, not ordinary project configuration. See the Maven settings reference and configuration guide.

Set a persistent location in settings.xml

For a setting that should apply to one developer across projects, edit the user settings file, normally ~/.m2/settings.xml. Add <localRepository> directly inside the root <settings> element:

#	Preview	Product	Price
1		Maven: The Definitive Guide	$40.05	Buy on Amazon
2		Mastering Apache Maven 3	$50.99	Buy on Amazon
3		Apache Maven Simplified: A Practical Guide to Build Automation, Dependency Management, and Project...	$12.20	Buy on Amazon
4		Introducing Maven: A Build Tool for Today's Java Developers	$28.85	Buy on Amazon
5		Apache Maven Cookbook	$55.32	Buy on Amazon

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>/opt/maven-cache/repository</localRepository>
</settings>

Use an absolute path, and ensure the account running Maven can create and write to it. Examples include /var/cache/maven/repository on Linux, /Volumes/BuildDisk/maven-repository on macOS, and C:/maven/repository on Windows. Forward slashes are a clear option for Windows paths in XML.

The default is ${user.home}/.m2/repository. If you already have a settings file, edit it rather than replacing it: preserve any existing mirrors, proxies, server credentials, and profiles. Maven can also read installation-level settings from ${maven.home}/conf/settings.xml; user and installation settings are merged, with user settings taking precedence. Details are in the settings reference.

#1 Best Overall

Sale

Maven: The Definitive Guide

$40.05

Buy on Amazon

Use a different repository for one build or CI job

To override the location for a single invocation, use Maven’s maven.repo.local user property:

mvn -Dmaven.repo.local=/tmp/maven-repository clean verify

For example:

# Linux or macOS
mvn -Dmaven.repo.local="$PWD/.m2/repository" verify

# Windows Command Prompt
mvn -Dmaven.repo.local=C:maven-cacherepository verify

# PowerShell
mvn -Dmaven.repo.local="$env:USERPROFILEmaven-cacherepository" verify

This is often the least disruptive CI option: put the desired path in the job’s Maven command or configuration instead of changing a developer’s settings. In containers, the cache is lost when an ephemeral container is removed unless the chosen directory is mounted or retained by the CI system. Maven documents the property in its configuration options.

You can also select a specific user settings file for an invocation:

Rank #2

Mastering Apache Maven 3

$50.99

Buy on Amazon

mvn -s /path/to/settings.xml verify

This is useful when a CI job needs its own settings. Protect any credentials in that file and avoid printing unredacted settings in public logs.

Project-level options

Maven 3: .mvn/maven.config

For Maven 3.3.1 and later, a project can supply Maven command-line options in .mvn/maven.config. For example:

# .mvn/maven.config
-Dmaven.repo.local=/workspace/project/.m2/repository

Maven 3.9.0 and later require each argument in this file to be on its own line. This is a project-level way to pass an option; it does not add a local-repository setting to the POM. See Maven’s configuration guide.

Rank #3

Apache Maven Simplified: A Practical Guide to Build Automation, Dependency Management, and Project Lifecycle

$12.20

Buy on Amazon

Think carefully before committing a path here. A fixed path such as /Users/alice/... or C:UsersAlice... will not work for other machines. For a portable project, prefer user settings, or have CI supply an absolute path appropriate to its workspace. Relative-path behavior can depend on how and where Maven is launched, so an absolute path is the safer choice when you control the environment.

Maven 4: .mvn/settings.xml

Maven 4 adds project settings support, conventionally through .mvn/settings.xml. That file can contain a <localRepository> setting, using the Maven 4 settings namespace, for example:

<settings xmlns="http://maven.apache.org/SETTINGS/2.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/2.0.0 https://maven.apache.org/xsd/settings-2.0.0.xsd">
  <localRepository>/workspace/project/.m2/repository</localRepository>
</settings>

This is specifically a Maven 4 feature, not a general solution for teams building with Maven 3. Confirm that the Maven version used by every relevant developer and CI job supports project settings. A committed machine-specific path is still non-portable, and settings files must not expose secrets. See the Maven 4 configuration reference.

Rank #4

Sale

Introducing Maven: A Build Tool for Today's Java Developers

$28.85

Buy on Amazon

Why the POM approaches don’t work

This only defines a project property; it does not tell Maven to relocate its cache:

<properties>
  <maven.repo.local>/tmp/maven-repository</maven.repo.local>
</properties>

Likewise, this is not a local-cache setting:

<repositories>
  <repository>
    <id>local</id>
    <url>file:///tmp/maven-repository</url>
  </repository>
</repositories>

The <repositories> section lists remote artifact sources Maven may consult; a file:// URL is a file-based repository source, not a command to move Maven’s local repository. Maven downloads from remote repositories into its local cache, whose location is configured separately. Use <repositories> for dependency sources, <pluginRepositories> for plugin sources, <distributionManagement> for deployment destinations, and <localRepository> in settings for the local cache. The distinction is described in Maven’s repository guide.

Verify the active location

Run a build with the intended setting, then check that Maven creates or writes to the specified directory:

Best Value

Sale

Apache Maven Cookbook

$55.32

Buy on Amazon

mvn -Dmaven.repo.local=/tmp/test-maven-repository verify

For diagnostics, Maven’s debug output can show configuration and repository behavior:

mvn -Dmaven.repo.local=/tmp/test-maven-repository -X validate

You can inspect effective settings with:

mvn help:effective-settings

Effective settings output can contain sensitive server configuration and private repository details. Redact it before sharing or attaching it to a bug report. If an IDE still uses the old location, check which Maven installation, settings file, and runner configuration that IDE uses; IDEs do not necessarily invoke Maven with the same configuration as your terminal.

Troubleshooting common problems

• XML parse error: Ensure <localRepository> is inside the root <settings> element and that the file remains valid XML. Add the element to the existing file rather than duplicating the root.
• Path is rejected or not used: In settings.xml, use an absolute path and check for a typo or an incorrect path for your operating system.
• Permission denied: Confirm the Maven process’s user can create directories and write files there. A previous build may have created files owned by another user, or a mounted directory may be read-only.
• The new repository is empty: Changing the path does not move existing artifacts. Maven will fetch what it needs into the new cache. Alternatively, copy the old repository while preserving its directory structure and permissions; an incomplete copy can lead to resolution failures.
• Builds behave differently in an IDE or CI: Check the actual Maven executable, settings file, working directory, and command-line options used by that runner. Make the intended path explicit for each environment.
• Concurrent jobs share a cache: Avoid assuming that several Maven processes can safely write to one shared network directory. Permissions, locking, and filesystem behavior matter; test the arrangement or use separate job/workspace caches.

If you want to retry downloads after a repository copy or resolution problem, -U forces update checks, but it can increase network traffic and is not a universal repair:

mvn -U -Dmaven.repo.local=/new/path verify

For a clean test cache, use a new directory rather than deleting a repository whose contents you may still need. If you decide to remove a cache, confirm that re-downloading dependencies and plugins is acceptable first.

Local cache, mirror, or shared repository?

Changing maven.repo.local changes where Maven stores its local cache; it does not change which server Maven contacts. If Maven should download through a company mirror, configure <mirrors> in settings instead. A mirror redirects remote repository access, while a repository manager can serve as shared infrastructure for proxying or hosting artifacts. These solve different problems; see the mirror guide.

A local repository also holds artifacts installed locally, so it is not automatically a safe team-wide artifact server. For team sharing, use appropriate remote repository infrastructure rather than pointing many concurrent builds at one writable network folder without validating its behavior.

Quick Recap

SaleBestseller No. 1

Maven: The Definitive Guide

$40.05

Bestseller No. 2

Mastering Apache Maven 3

$50.99

Bestseller No. 3

Apache Maven Simplified: A Practical Guide to Build Automation, Dependency Management, and Project Lifecycle

$12.20

SaleBestseller No. 4

Introducing Maven: A Build Tool for Today's Java Developers

$28.85

SaleBestseller No. 5

Apache Maven Cookbook

$55.32

Which method should you choose?

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.