Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 41 ยท Repositories

Repositories and the Local Cache

Learn how Maven repositories work: the ~/.m2 local cache, Maven Central, how a GAV becomes a file path, checksums, update policies and offline mode.

When you declare a dependency, you give Maven three coordinates and nothing else: no URL, no file name, no download link. Yet Maven finds the right JAR on the right server every time. The trick is that Maven repositories follow one strict layout, so a set of coordinates can be turned into a file path by a simple formula.

In this lesson you will learn the two kinds of repository (your local cache and remote servers such as Maven Central), the layout formula, how Maven checks that downloads are intact, and what happens when you are offline. Understanding this removes most of the mystery from "why is Maven downloading things" and "why does it say it cannot find my artifact".

Maven cannot run in your browser, so the commands, paths and XML on this page are read-only. The three Java programs are stand-ins: they build repository paths, compute and verify checksums with the JDK's MessageDigest, and simulate the order in which Maven looks for a file. They illustrate the rules and are not Maven's code.

Two kinds of repository

Where artifacts live

Local repository A cache folder on your machine.
Remote repository A server you download from.
Maven Central The public remote everyone uses by default.
Company repository A private server such as Nexus or Artifactory.

Maven asks the local one first.

1 / 2

The local repository lives in your home directory: ~/.m2/repository on macOS and Linux, and C:\Users\<you>\.m2\repository on Windows. Everything Maven downloads is stored there, and so is everything you build with mvn install. It is shared by all your projects: if two projects use the same library version, it is downloaded once. You can move it with <localRepository> in settings.xml (see settings.xml, Mirrors and Credentials) or per run with -Dmaven.repo.local=/some/folder, which CI systems use to get a clean or cached folder.

A remote repository is any server that speaks the same layout over HTTP. Maven Central (https://repo.maven.apache.org/maven2/, with the id central) is built into every Maven installation, so you never have to configure it. Companies often run their own repository manager that hosts private artifacts and caches Central.

From coordinates to a file

The layout formula is the heart of the whole system:

TEXT
<groupId with dots as slashes>/<artifactId>/<version>/<artifactId>-<version>[-<classifier>].<extension>

So org.apache.commons:commons-lang3:3.18.0 becomes:

TEXT
org/apache/commons/commons-lang3/3.18.0/commons-lang3-3.18.0.jar
org/apache/commons/commons-lang3/3.18.0/commons-lang3-3.18.0.pom

The same path works under the local repository folder and under a remote base URL. A browser can fetch https://repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.18.0/ and list the files. Look at one of those folders and you will usually find:

File Purpose
x-1.0.jar The library itself.
x-1.0.pom Its POM, read to find transitive dependencies.
x-1.0-sources.jar Source code (a classifier), used by IDEs.
x-1.0-javadoc.jar API documentation (a classifier).
x-1.0.jar.sha1 and other checksum files Fingerprints to verify the download.
x-1.0.jar.asc A PGP signature (published to Central).

At the artifact level (one folder up) there is also maven-metadata.xml, which lists the available versions. Maven reads it to resolve version ranges and to find the newest plugin version.

Here is the formula as a program, including a classifier. Add your own coordinates to the list and check the result against what you would expect on Central.

Java From GAV to repository path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Snapshots look different

A -SNAPSHOT version is a moving target (see Coordinates). When a snapshot is deployed to a remote repository, each upload gets a timestamped file name, such as x-1.0-20251102.103045-3.jar (date, time and a build number). The folder also has a snapshot-specific maven-metadata.xml that tells Maven which build is the newest. In your local repository the file is stored under the plain x-1.0-SNAPSHOT.jar name. This is also why snapshots are re-checked regularly and releases are not.

How Maven finds an artifact

For each artifact, Maven follows the same steps:

flowchart TD
    A["Need artifact"] --> B{"In local repo?"}
    B -- "yes" --> C["Use it"]
    B -- "no" --> D{"Offline mode?"}
    D -- "yes" --> E["Fail: not available offline"]
    D -- "no" --> F["Try remote repositories in order"]
    F --> G{"Found and checksum ok?"}
    G -- "yes" --> H["Store in local repo, then use it"]
    G -- "no" --> I["Fail: could not find or transfer artifact"]

Released versions found in the local repository are used as they are, with no network traffic.

Three consequences are worth remembering:

  • Releases are immutable. If 3.18.0 is in your local repository, Maven never asks the server again. That is why the second build is fast, and why a release must never be re-published with different content.
  • Snapshots are re-checked, by default once a day. Force a check with mvn -U (update snapshots). -U also retries things that failed recently.
  • Failures are cached. If a download failed, Maven remembers and may print "was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced". Run mvn -U ... to retry.

Checksums

Every file on Central comes with checksum files next to it (.sha1, and for many artifacts also .md5, .sha256 and .sha512). After a download, Maven computes the checksum of the received bytes and compares it with the published value. A mismatch means a corrupt or tampered transfer. By default Maven only warns on a mismatch; with the -C flag (strict checksums) it fails the build, and -c (lax) ignores checksum problems.

Checksums protect against accidents: a broken download, a half-written file. They do not prove who published a file, because an attacker who can replace the JAR could replace the checksum beside it. For authenticity there are PGP signatures (.asc) and the supply-chain practices discussed in Dependency Security and Supply Chain.

The next program computes a SHA-1 checksum of some bytes, "downloads" a file with the right checksum and a damaged copy, and verifies both.

Java Verify a download with a checksum

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Flip just one bit, and the SHA-1 changes completely. That avalanche effect is what makes checksums useful.

Offline mode and lookup order

With mvn -o (or <offline>true</offline> in settings.xml), Maven refuses to use the network. Builds work if everything they need is already in the local repository, and fail with a clear error otherwise. It is useful on a train or in a locked-down build environment. To warm the cache beforehand, run mvn dependency:go-offline; it downloads dependencies and plugins, though some dynamic plugin dependencies can still be missed, so a real offline build is the proper test.

The last program models the lookup: local repository first, then remote repositories in order, with an offline switch. Run it and read how the same request is answered in each situation.

Java Lookup order: local, then remotes, or offline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that lib-b:2.0 fails offline the first time and succeeds offline after one online run, because the online run cached it.

Practical tips

  • Corrupt or partial files: if a build complains about a bad POM or a truncated JAR, delete that one artifact's folder under ~/.m2/repository/... and build again with -U. You rarely need to delete the whole repository.
  • Your own libraries: mvn install copies your JAR and POM into the local repository, so other projects on your machine can depend on them. Only mvn deploy publishes to a remote (Publishing).
  • Extra remotes can be declared with <repositories> in a POM, but this is discouraged for libraries because it silently adds servers for everyone who depends on you. Prefer configuring repositories and mirrors in settings.xml.
  • Disk use: the local repository only grows. In CI, cache it (see Maven in CI and Faster Builds) but expire old caches sometimes.
  • Look inside: browsing ~/.m2/repository and reading the _remote.repositories file next to an artifact tells you which repository it came from.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where is the file for org.example:demo:1.2.0 (the JAR) expected inside a repository?

    Dots in the groupId become folders, then comes the artifactId, then the version folder, and finally artifactId-version.extension.
  2. 2. A release version is already in your local repository. What does Maven do when you build?

    Releases are treated as immutable, so a cached copy is trusted. Snapshots are the ones that get re-checked.
  3. 3. What does a checksum file like x-1.0.jar.sha1 protect against?

    Checksums detect accidental damage. They do not prove authorship, because an attacker could replace the checksum as well. Signatures address that.
  4. 4. You run mvn -o and a dependency is not in the local repository. What happens?

    Offline mode only uses what is already cached. Run an online build first, or use dependency:go-offline, to fill the cache.
  5. 5. Which flag forces Maven to re-check remote repositories for snapshots and retry cached failures?

    -U (update snapshots) makes Maven query the remotes again instead of trusting its cached state.

Summary

  • Maven uses a local repository (~/.m2/repository) and remote repositories, with Maven Central built in.
  • A repository path is built from the coordinates: group with slashes, artifactId, version, then artifactId-version[-classifier].ext.
  • Maven checks the local cache first, trusts releases once cached, and re-checks snapshots (-U forces it).
  • Checksums detect corrupt downloads. Signatures and other practices handle trust.
  • Offline mode (-o) uses only the cache, so warm it first.
  • mvn install writes to the local repository, and mvn deploy publishes to a remote one.

Next: settings.xml, Mirrors and Credentials