Repositories

Every time Maven resolves a dependency or a plugin, it queries one or more repositories. Understanding how these repositories work — where they are, how they are configured, and how to publish your own artifacts — is essential for professional Java development. This chapter covers the local cache, public remote repositories, private servers, and the configuration files that tie them together.

Prerequisites

• A working Maven installation
• Basic understanding of dependencies and pom.xml

The Local Repository

When Maven downloads an artifact, it stores a permanent copy on your machine. This cache is called the local repository and lives at ~/.m2/repository.

Directory Structure

Artifacts are stored in a directory tree that mirrors their GAV coordinates:

~/.m2/repository/
  com/
    fasterxml/
      jackson/
        core/
          jackson-databind/
            2.17.0/
              jackson-databind-2.17.0.jar
              jackson-databind-2.17.0.pom
              jackson-databind-2.17.0-sources.jar
              _remote.repositories
              maven-metadata-central.xml

The folder path follows groupId/artifactId/version/. Inside each version folder, you will find:

Cleaning the Local Repository

If you suspect a corrupted download, delete the specific artifact folder:

# Remove a specific artifact from the cache
rm -rf ~/.m2/repository/com/fasterxml/jackson/core/jackson-databind/2.17.0

To wipe everything and start fresh:

# Delete the entire local repository (Maven will re-download on next build)
rm -rf ~/.m2/repository

Maven Central

Maven Central is the default public repository for the Java ecosystem. It hosts millions of open-source libraries and is maintained by Sonatype. Unless you configure something else, every Maven build queries Central for dependencies it cannot find locally.

You do not need to declare Maven Central in your pom.xml — it is wired into Maven's Super POM. However, if you add custom repositories, Maven stops inheriting the default list and you must include Central explicitly:

<repositories>
    <repository>
        <id>central</id>
        <name>Maven Central</name>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</repositories>

Configuring Additional Remote Repositories

Some libraries are not published to Maven Central. Spring milestones, JBoss artifacts, and corporate internal libraries often live in dedicated repositories. You declare these in your pom.xml:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

Maven checks repositories in the order they are declared. Once an artifact is found, the search stops. For snapshot artifacts, Maven also checks whether a newer build is available on every run.

Mirror Configuration for Faster Downloads

If you are located far from Maven Central's servers, downloads can be slow. A mirror is an alternative server that hosts a copy of Central's content. You configure mirrors in ~/.m2/settings.xml, not in pom.xml, because mirror choice is a personal or organizational preference, not a project requirement.

Aliyun Mirror (China)

For developers in mainland China, the Aliyun mirror is significantly faster than Central:

<settings>
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <name>Aliyun Maven</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
</settings>

The <mirrorOf>central</mirrorOf> line tells Maven: "Whenever you would normally ask Maven Central for an artifact, ask this mirror instead."

Private Repositories (Nexus / Artifactory)

Public repositories are fine for open-source libraries, but companies need a place to host their own proprietary artifacts. A private repository server fills this role. The two most popular options are:

A private repository typically serves three purposes:

1. Proxy — caches public artifacts so the team does not re-download them from the internet
2. Host — stores internal artifacts that should not leave the company network
3. Group — combines multiple proxied and hosted repositories under a single URL

Configuring a Private Repository

Add the repository to pom.xml:

<repositories>
    <repository>
        <id>company-releases</id>
        <name>Company Release Repository</name>
        <url>https://nexus.company.com/repository/maven-releases/</url>
    </repository>
    <repository>
        <id>company-snapshots</id>
        <name>Company Snapshot Repository</name>
        <url>https://nexus.company.com/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Publishing Artifacts with mvn deploy

Once your project is ready to share, you publish it with mvn deploy. This command runs the full lifecycle up to the deploy phase and uploads the artifact to a remote repository.

Configuring the Distribution Target

Add <distributionManagement> to your pom.xml:

<distributionManagement>
    <repository>
        <id>company-releases</id>
        <name>Company Release Repository</name>
        <url>https://nexus.company.com/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
        <id>company-snapshots</id>
        <name>Company Snapshot Repository</name>
        <url>https://nexus.company.com/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

The snapshotRepository is used when your version ends in -SNAPSHOT. Release repositories typically reject snapshot uploads, and vice versa.

Authentication in settings.xml

Passwords do not belong in pom.xml. Store credentials in ~/.m2/settings.xml under <servers>:

<settings>
    <servers>
        <server>
            <id>company-releases</id>
            <username>deployer</username>
            <password>{your-encrypted-or-plain-password}</password>
        </server>
        <server>
            <id>company-snapshots</id>
            <username>deployer</username>
            <password>{your-encrypted-or-plain-password}</password>
        </server>
    </servers>
</settings>

Deploying

With everything configured, run:

# Build, test, and publish the artifact
mvn clean deploy

If authentication succeeds, your artifact appears in the remote repository and becomes available to other projects.

FAQ

Why does Maven re-download artifacts I already have?

For release versions, it should not. For snapshots, Maven checks for updates on a schedule defined by <updatePolicy> (default: daily). You can force an update with mvn clean install -U.

Can I use multiple mirrors at once?

Yes. Each mirror can match a different <mirrorOf> pattern. For example, one mirror might handle central while another handles a specific corporate repository. If two mirrors match the same repository, Maven uses the first one declared in settings.xml.

What is the difference between <repositories> and <pluginRepositories>?

<repositories> is for project dependencies. <pluginRepositories> is for build plugins. They are configured separately because some organizations restrict which plugins developers can use. If you do not declare <pluginRepositories>, Maven uses <repositories> for both.

How do I prevent Maven from contacting remote repositories during a build?

Run in offline mode:

# Use only the local repository
mvn clean install -o

This fails if a required artifact is missing from the cache, but it is useful on airplanes or in restricted network environments.

Should I publish SNAPSHOT versions to a remote repository?

Yes, during active development. Snapshots let team members consume the latest work-in-progress without waiting for a formal release. Just remember that snapshot artifacts can change at any time, so they are unsuitable for production deployments.