mvn -o (--offline): build without accessing remote repositories
- tool
- Maven
- command
- mvn
- flag
- -o, --offline
- default
- off (remote repositories are used when needed)
mvn -o package (long form --offline) tells Maven to use only what is already in the local repository (~/.m2/repository) and never contact remote repositories. Builds are faster, work without a network and cannot pick up a new snapshot by accident. Anything missing from the local repository makes the build fail with a message saying Maven cannot access the repository in offline mode and the artifact has not been downloaded from it before.
Prepare, then build offline
mvn dependency:go-offline # online: download dependencies and plugins
mvn -o clean verify # offline from now ondependency:go-offline resolves the project's dependencies and the plugins of the build, but plugins or dependencies that are only resolved during execution (some report plugins, dynamically added dependencies) can still be missing. Running the exact build once online is the more reliable preparation.
Offline versus online behaviour
| Situation | Online build | mvn -o |
|---|---|---|
| Dependency already in ~/.m2 | Used | Used |
| Dependency missing | Downloaded | Build fails |
| SNAPSHOT older than the update interval | Checked remotely | Local copy used as is |
| New plugin version or prefix | Resolved remotely | Fails if not cached |
| Repository manager or proxy down | Build fails | Not affected |
Other ways to switch it on
| Method | Scope |
|---|---|
| -o / --offline | One build |
| <offline>true</offline> in ~/.m2/settings.xml | Every build of this user |
| .mvn/maven.config containing -o | Every build of the project |
| -nsu, --no-snapshot-updates | Online, but never update snapshots |
.mvn/maven.config holds command-line options for a project; putting -o there is handy for air-gapped environments but confusing for everyone else, so prefer the command line.
Pitfalls
- Offline mode cannot fix a corrupt or partial download in the local repository; delete that artifact's folder while online and build again.
-oand-Ucontradict each other; offline mode wins and no updates are checked.- Plugin prefixes (
mvn versions:...) need repository metadata. In offline mode an unknown prefix fails with No plugin found for prefix. - CI caches of
~/.m2/repositorymake online builds fast as well, without the risk of a missing artifact; offline mode is mainly for machines without network access. - Gradle has the same switch: gradle --offline.
FAQ
How do I prepare a project for an offline Maven build?
Run mvn dependency:go-offline (or simply a full mvn verify) once while online. It downloads dependencies and plugins into ~/.m2/repository; later builds with -o use that cache.
Why does mvn -o fail although the jar is in ~/.m2?
Maven also records which remote repository an artifact came from (the _remote.repositories file). If the project now uses a different repository id, the cached file does not count for it. Re-download it online once with the current settings.
Can I make offline mode permanent?
Yes, with <offline>true</offline> in settings.xml. Remember to remove it again, otherwise every new dependency fails to resolve.