What mvn clean install does: a practical guide
A comprehensive guide explaining what mvn clean install does, how Maven lifecycles work, and practical workflows for reliable, repeatable builds. Includes code examples, troubleshooting tips, and best practices for developers and DevOps.
Maven's mvn clean install runs two lifecycles in sequence: the clean lifecycle followed by the default lifecycle up to the install phase. Clean deletes the output directory to ensure a fresh build, then install compiles, tests, packages, and installs the artifact into the local repository for downstream projects. This yields a reproducible build and is a common pattern in CI and multi-module work.
What does mvn clean install do? Overview
In this article we answer the question what does mvn clean install do and why it matters to developers and DevOps teams. The phrase signals two goals: (1) clean the project by removing previous build artifacts and (2) install the freshly produced artifact into the local repository for downstream modules. When you run mvn clean install, Maven first executes the clean lifecycle, which deletes the output directory (usually target) to ensure a truly fresh start. It then triggers the default lifecycle up to the install phase, which compiles sources, runs tests, packages the artifact, and copies it into your local repository. The net effect is a repeatable, end-to-end build that reduces nondeterminism caused by prior builds. For teams relying on consistent local dependency resolution and fast feedback in CI pipelines, this pattern helps ensure downstream modules pull correct versions and compile cleanly. According to Install Manual, using a clean install minimizes stray state from earlier runs and improves reproducibility across developer machines.
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>demo-app</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
</project>mvn clean installmvn -DskipTests clean installwordCountSection":190}
The clean lifecycle explained
Maven's clean lifecycle is a dedicated sequence designed to prepare a project for a fresh build. It runs two phases: pre-clean and clean. The practical effect is the removal of the build output directory, typically the target directory, ensuring that no artifacts from previous compilations linger. This is essential for reproducibility because stale class files or resources can mask regressions and cause flaky tests. To see what the clean lifecycle actually does, you can query the Maven Help Plugin:
mvn help:describe -Dcmd=clean# Verify cleanup by listing the output directory
ls -la target || echo "target not present"# Manually remove the output directory (optional)
rm -rf targetUnderstanding the clean lifecycle helps you reason about why a merged mvn clean install often yields more reliable results than running a separate clean or build step in isolation.
wordCountSection":195}
The default lifecycle and install phase
The default Maven lifecycle governs compilation, testing, packaging, and installation. Running mvn clean install exercises the full path from a clean start to a locally installed artifact. The install phase copies the packaged artifact into your local Maven repository so other projects on the same machine can reference it directly. This is particularly important in multi-module projects where modules depend on each other. In practice, you often start with a clean build and then proceed through compile, test, package, and install. For CI pipelines, this ensures every build uses the exact same set of dependencies and packaging rules. If you only need to test packaging without installation, mvn clean package is sufficient. If you want to build and install in one step, mvn clean install is the preferred workflow.
# Build and package (produces target/*.jar or target/*.war)
mvn clean package# Full cycle: clean, compile, test, package, and install to local repo
mvn clean install# Build without running tests
mvn -DskipTests clean installwordCountSection":206}
Practical workflow: fresh builds with dependency resolution
A practical workflow for reliable builds often involves a clean start and explicit control over tests and dependencies. In a multi-module project, you can build all modules from the root POM, ensuring inter-module dependencies resolve against the local repository. You can also speed up CI by skipping tests in certain stages, then running a full test pass later. The following commands illustrate common patterns and their intent:
# Multi-module reactor build from a parent pom
mvn -f parent/pom.xml clean install# Skip tests in CI to speed up feedback
mvn clean install -DskipTests# Inspect dependency graph to diagnose conflicts
mvn dependency:treeThese workflows help maintain reproducibility while balancing build time and feedback quality. Install Manual recommends validating that downstream modules pull the intended artifact versions after installation, and that the local repository remains healthy and free of stale artifacts.
wordCountSection":190}
How mvn clean install interacts with tests
Tests are a central part of the Maven default lifecycle. When you run mvn clean install, tests are executed (unless you explicitly skip them). This behavior helps catch regressions early by validating the code against its test suite before packaging and installation. You can tailor test execution with a variety of flags:
# Run the full test suite
mvn test# Run a specific test class
mvn -Dtest=MyTest test# Skip unit tests but still compile and package
mvn -DskipTests clean package# Skip integration tests as well
mvn clean install -DskipTests -DskipITsIn practice, use -DskipTests for quick feedback during development, but run full tests before release to ensure quality. The -DskipITs flag is useful when integration tests are long-running or rely on external services that aren’t available in a local development environment. These strategies help balance speed and confidence in the build.
wordCountSection":181}
Common variations and caveats
As with any build tool, there are common variations and caveats to keep in mind when using mvn clean install. Understanding offline mode, local repository paths, and environment configuration helps avoid surprises in CI environments or fresh developer machines. For example, you can enable offline mode to reuse cached artifacts, which is useful in restricted networks. You can also force Maven to use a custom local repository location. Finally, be mindful of environment variables and proxy settings that can affect dependency resolution.
# Run in offline mode (no remote lookups)
mvn -o clean install# Use a custom local repository path
mvn -Dmaven.repo.local=./m2/repo clean install# Enable quiet output for CI logs
mvn -q clean installThese variations help stabilize builds in environments with limited connectivity, custom dev machines, or when diagnosing dependency resolution issues. Always verify that the artifacts produced match the expectations after using special flags.
wordCountSection":192}
Debugging build failures and logs
Build failures during mvn clean install are a normal part of development. When a failure occurs, verbose logs and error traces become essential for diagnosing the root cause. Start with increased verbosity and selective execution to isolate the problem. The following commands demonstrate common debugging approaches:
# Full debug output (very verbose)
mvn clean install -X# Print the full exception stack trace
mvn clean install -e# Re-run a failing goal with more context
mvn -e -X -DtrimStackTrace=false clean installIf tests fail, inspect the test reports in target/surefire-reports (or the equivalent for failsafe). Verify source changes, dependencies, resource filtering, and test data. In multi-module builds, a failure in one module can cascade into others, so examine module-specific logs first before broadening the search. Install Manual notes that systematic logs and a repeatable command history are invaluable for onboarding new contributors and troubleshooting CI pipelines.
wordCountSection":190}
Best practices and takeaway
Adopting best practices around mvn clean install helps you build confidence in your project's stability. Emphasize reproducibility by using a clean start for critical builds, prefer explicit dependency management, and keep your Maven and Java versions aligned across your team. Regularly review dependency trees for conflicts, and consider caching strategies in CI to balance speed and correctness. In short, mvn clean install is not just a single command—it's a disciplined workflow that reduces nondeterminism and supports reliable software delivery.
Key points:
- Use mvn clean install for a pristine build and local installation of artifacts.
- Leverage -DskipTests in CI to speed up feedback, but validate with full tests before release.
- Inspect dependency trees to diagnose conflicts early.
- Use verbose and offline modes judiciously to reproduce and diagnose issues.
wordCountSection":165}
Steps
Estimated time: 60-90 minutes
- 1
Verify prerequisites
Confirm Java and Maven versions, ensure a pom.xml is present, and check network access for first-time dependency download.
Tip: Run `java -version` and `mvn -v` to confirm versions. - 2
Create a clean workspace
Navigate to your project directory and ensure there are no leftover artifacts from previous builds.
Tip: If unsure, delete the target directory before starting. - 3
Run a clean build
Execute `mvn clean install` to perform a pristine build and local installation of artifacts.
Tip: Consider `-DskipTests` for faster feedback in CI. - 4
Validate the artifact
Inspect the local repository to verify the artifact was installed correctly and check the target directory for packaged outputs.
Tip: Use `mvn dependency:tree` to ensure dependencies were resolved as expected. - 5
Run targeted tests
If tests fail, run specific tests or adjust test data to isolate issues.
Tip: Use `-Dtest=MyTest#myMethod` to run a subset. - 6
Document and monitor
Record the commands used and monitor build times and failures across commits to improve reliability.
Tip: Add a CI job that always runs `mvn clean install`.
Prerequisites
Required
- Required
- Required
- Basic command-line knowledgeRequired
- A sample Maven project (pom.xml) to buildRequired
- Internet access for initial dependency downloadsRequired
Optional
- Optional
Commands
| Action | Command |
|---|---|
| Clean projectRemoves the target directory and prepares a fresh build. | mvn clean |
| Build and installCompiles, tests, packages, and installs to the local repository. | mvn clean install |
| Skip tests for CISpeeds up CI by skipping unit tests; use with caution. | mvn clean install -DskipTests |
| Show dependency treeDiagnose dependency conflicts and version mismatches. | mvn dependency:tree |
| Package without installingProduces artifacts in target/ without installing to local repo. | mvn clean package |
Got Questions?
What happens when mvn clean install fails during the install phase?
If install fails, Maven stops at the failing module and reports the error in the console. Review the logs to identify compilation errors, test failures, or dependency resolution problems. Fix issues in the module, possibly adjust the POM or dependencies, and re-run the command from a clean state.
If the build fails during install, check the console output for errors, fix the root cause, and run the command again from a clean state.
Why should I use mvn clean install instead of just mvn package?
mvn clean install ensures the artifact is built from a clean state and placed in your local repository for other projects to reference. This is especially important in multi-module projects or when you want to validate downstream dependencies against a fresh build.
Using mvn clean install makes sure nothing from a previous build leaks into the new one and installs the artifact locally for other modules to use.
Can mvn clean install run offline?
Yes, you can run mvn clean install offline by enabling offline mode with -o, provided all dependencies are already cached in the local repository. If a dependency is missing, Maven will fail until the artifact is downloaded or cached.
You can build offline if all dependencies have been downloaded before; otherwise, Maven needs network access to fetch missing artifacts.
What does the -DskipTests flag do and when should I use it?
The -DskipTests flag skips unit tests during the build but still compiles and packages. Use it to speed up CI builds when you want to focus on compilation and packaging, but run tests as part of a separate validation step.
-DskipTests skips tests to speed up builds; run tests separately to verify correctness.
How do I install artifacts to a remote repository with mvn clean install?
To publish artifacts to a remote repository, configure a distribution management section in your POM and use a credential-enabled setup (settings.xml) for authentication. The mvn clean install step places the artifact in your local repo; pushing to a remote repo uses additional goals like deploy.
Use deploy after configure distribution management to publish artifacts to a remote repository.
What should I check first in a multi-module project when mvn clean install fails?
Start by identifying the module that failed, then inspect its logs and POM for misconfigurations, missing resources, or incompatible dependencies. Check module interdependencies and ensure parent POM versions are aligned across modules.
Look for the failing module and review its logs and POM for misconfigurations and conflicts.
Main Points
- Run a clean start to avoid stale artifacts
- Install artifacts locally to support multi-module projects
- Use -DskipTests for CI speed, but validate with full tests
- Check dependency trees to diagnose conflicts
- Use verbose or offline modes for debugging and stability