Maven Versions, SNAPSHOTs & Ranges

A release version, such as 1.2 or 2.0-beta-1, names one immutable build. Once it is published, every consumer gets the same bytes for it, and a repository manager normally refuses to overwrite it. A SNAPSHOT version is a version that ends with the literal string -SNAPSHOT, such as 1.0-SNAPSHOT. It means "the development line leading to 1.0", a moving target that is rebuilt many times before the release. Because of that, Maven treats the two differently in three places:

The related coordinates of the build that resolve to a SNAPSHOT are in the POM, and the versions of the tools that read them are on Versions & Release History.

The POM of tidepool-data has version 1.0-SNAPSHOT and a distributionManagement section pointing to a file:// repository (the section is the subject of Install, Deploy & Distribution Management):

Maven chooses snapshotRepository for a SNAPSHOT version and repository for a release. The class Data had a method returning "v1". The library was deployed (mvn deploy), then the method was changed to return "v2" and the library was deployed again. This is the listing of the repository after the second deployment (the .md5 and .sha1 checksum files were left out):

No file is called tidepool-data-1.0-SNAPSHOT.jar. Maven replaced SNAPSHOT with the deployment time in UTC, 20261016.123517, and a build number, 2, that it increments from the metadata already in the repository (it starts at 1 for the first deployment). The transformation is 1.0-SNAPSHOT to 1.0-${YYYYMMDD.HHMMSS}-${counter}, and the timestamp is the time the Maven session was created, so every file of one deployment carries the same value. Each deployment adds files; it does not replace the previous ones. The Maven 3.10.0 log of the last step printed Skipping already-deployed io.tidepool:tidepool-data:1.0-SNAPSHOT for the deploy goal of the Deploy plugin 3.2.0 even though the files above had been uploaded; I did not investigate that message further, and the listing is what was verified.

The part of the version that the POM declares, 1.0-SNAPSHOT, is called the baseVersion. The timestamped 1.0-20261016.123517-2 is the version of the file. Two metadata files link them, and they are the reason a SNAPSHOT works at all.

Source: Maven remote repositories: The baseVersion artifact property

The consumer tidepool-app declares the dependency io.tidepool:tidepool-data:1.0-SNAPSHOT and the file:// repository with snapshots enabled. Resolving it with an empty local repository (the output was trimmed to the lines that matter):

The order of the requests is the whole mechanism. Maven asked for the version-level maven-metadata.xml first, read from it that 1.0-SNAPSHOT currently means 1.0-20261016.123517-2, and only then downloaded that POM and that JAR. Everywhere in the build, the dependency is still called 1.0-SNAPSHOT: dependency:list prints the baseVersion, not the timestamp.

The local repository then holds, next to the timestamped files, copies named tidepool-data-1.0-SNAPSHOT.jar and .pom, and the bookkeeping files of the resolver. The build classpath uses the 1.0-SNAPSHOT copy:

(The .sha1 files were left out.) maven-metadata-tidepool-local.xml is the cached metadata, named after the repository id. _remote.repositories records which repository each file came from, and resolver-status.properties records when the metadata was last checked. Their format is an internal detail of the Maven Resolver and can change. After a few updates the directory holds one pair of files for every build number that was ever downloaded; Maven does not clean old ones (see the listing in the next section), which is one reason to purge a local repository from time to time with dependency:purge-local-repository.

Source: Maven remote repositories: Consuming snapshot artifacts

A snapshot is a moving target, so the question is how often Maven looks for a newer build. That is the update policy of a repository, set separately for <releases> and <snapshots>. The values are always, daily (the default), interval:X (where X is a number of minutes) and never, which downloads only if the file does not yet exist in the local repository. It applies to both artifacts and metadata. The command line overrides it: -U (--update-snapshots) "forces a check for missing releases and updated snapshots on remote repositories", whatever the policy says.

The experiment used the repository entry of the consumer POM, the same snapshot-enabled tidepool-local as before, and changed updatePolicy between runs. Between the runs new builds of tidepool-data were deployed (the consumer’s local repository kept the older ones). The count is the number of download lines for tidepool-local in the log:

The log of the always run, trimmed to the lines for tidepool-local:

After those runs the consumer’s local repository held every build that had been downloaded, plus the copy that is used:

Maven 3.9.16 and Maven 4.0.0-rc-7, each with an empty local repository, downloaded the same metadata and build 5 and printed the same resolved dependency. The practical rules that follow:

You can pin a snapshot to one build by writing the timestamped version in the dependency:

This resolved against the repository above and downloaded build 3 exactly. It is a lock-down of the bytes, not a promotion to a release: dependency:list still printed io.tidepool:tidepool-data:jar:1.0-SNAPSHOT:compile, and the enforcer’s requireReleaseDeps rule still rejected the project. The same rule on the normal 1.0-SNAPSHOT declaration (with -Denforcer.rules=requireReleaseDeps; the older -Drules still works but prints a deprecation warning):

The pinned timestamped version failed the same rule. The Maven Release Plugin makes the same check for you before it tags a release (that plugin was not run here; see Releasing). Only rarely is a lock-down the right answer: the repository may delete old snapshot builds, and a timestamped version in a POM is still a SNAPSHOT for every tool that matters. The rest of the toolbox for this is the Enforcer.

Source: Maven remote repositories: Consuming snapshot artifacts, Enforcer rule: requireReleaseDeps

A <version> element in a dependency is a version requirement, not necessarily a single version. It is soft when it is a plain version, and hard when it is written with brackets. A soft requirement is a recommendation: Maven uses it if nothing else in the graph asks for a different version nearer to the root. A hard requirement must be honoured; Maven picks the highest version of the artifact that satisfies every hard requirement, and the build fails if no version does.

Square brackets are inclusive, parentheses exclusive. The tidepool-units library was deployed as 1.0, 1.1, 1.2, 2.0, 2.1-beta-1, then 1.3, then 1.0.1 (that odd order matters later). A consumer whose dependency version was the property ${range} was resolved for each requirement with this small script, which ran mvn -B -U -Drange="$r" dependency:list (-U so that the metadata is always fresh) and kept the resolved version:

The first row is a soft requirement and so behaves like any fixed version. For [3.0,) the script printed nothing because the build failed; the error was

Two results deserve a second look. [1.1,) selected 2.1-beta-1, a pre-release, because an open-ended range takes the highest version in the repository, and by the order rules below 2.1-beta-1 is greater than 2.0. And [1.0,2.0) selected 1.3, even though 1.3 was deployed after 2.0, because the choice is by version order, not by deployment order. The script is this page’s own lab setup, not an example from the Maven documentation.

Source: POM reference: Dependency version requirement specification

Every comparison above, from "highest version in a range" to "which snapshot is newer", uses one algorithm, implemented by the class org.apache.maven.artifact.versioning.ComparableVersion in the maven-artifact library. It is not Semantic Versioning: Maven compares versions as sequences of tokens, and it pays no attention to semantic versioning 2.0.0 ideas such as the plus sign or build identifiers. If your versions follow Semantic Versioning 1.0.0 and use lower-case letters, the result usually agrees with the semver precedence rules. The rules, summarised from the specification:

The class can be called directly to check a version list. The Maven 3.10.0 lib/maven-artifact-3.10.0.jar was put on the class path of a short program that sorts its arguments with Collections.sort and prints them, with = between versions that compare equal and < otherwise:

Notice: 1.9 < 1.10 (numbers, not strings), 1.0-SNAPSHOT is below 1.0, 1.0-sp1 is above it, an unknown qualifier (1.0-foo) is above the service pack, and a number after a hyphen (1.0-1) is above an unknown qualifier. Case does not matter (rc1 = RC1). The same list compared with the maven-artifact jar of Maven 3.9.16 and of Maven 4.0.0-rc-7 gave an identical output (checked with md5 of the output, with three extra arguments, 1.0-20261016.123517-2, 1.0.RC1 and 1.0+build5). The program is this page’s own lab tool, not an example from the Maven documentation.

Two further results from the program, using longer lists. The first shows how pre-releases, a service pack and a timestamped snapshot version line up; the second how the choice of separator matters.

The first line has a surprise: the timestamped version 1.0-20261016.123517-2 is greater than 1.0, 1.0-sp1 and everything else of the 1.0 line, because after the hyphen it is a number. That is exactly why Maven keeps the baseVersion (1.0-SNAPSHOT) for all the logic that needs an order, and why a timestamp must never appear in a range. On the second line a plus sign has no special meaning: 1.0+build5 and 1.0+build6 are ordered like any other qualifier text and both sort above 1.0, whereas Semantic Versioning 2.0.0 ignores build metadata when it compares.

The canonical form that ComparableVersion keeps internally can be printed with getCanonical(), which makes the trimming visible:

The specification recommends a few habits that avoid the traps above: use alpha, beta and milestone rather than ea or preview; write 1.0.0-RC1 rather than 1.0.0.RC1; prefer RC to the discouraged CR; do not use final, ga or release (no qualifier is the release); do not use SP (increment the patch version instead); and avoid non-ASCII characters in versions. The project-wide naming conventions are on Philosophy, Coordinates & Directory Layout.

Source: POM reference: Version order specification, POM reference: Version order testing

A reproducible build gives the same dependencies from the same inputs. Both features give that up:

Practical guidance that follows from these results:

The Ivy side is on Ivy: Conflicts & Versions, the Gradle side on Platforms, Constraints & Rich Versions and Dependency Locking, Verification & Caching. The tool-neutral discussion of conflicts and ranges is on Dependency Management Fundamentals.