Introduction

The difference is one extra lifecycle phase. mvn clean package compiles your code, runs tests, and creates the artifact (JAR, WAR, etc.) in the target/ directory. mvn clean install does everything package does and then copies that artifact into your local Maven repository (~/.m2/repository), making it available as a dependency for other projects on the same machine.

How the Maven Default Lifecycle Works

Maven organizes work into a sequence of phases. When you invoke a phase, Maven executes every phase that comes before it in the sequence. The relevant portion of the default lifecycle looks like this:

validate -> compile -> test -> package -> verify -> install -> deploy

Running mvn package triggers validate, compile, test, and package. Running mvn install triggers all of those plus verify and install. This is why install is a strict superset of package.

The clean prefix is a separate lifecycle. Adding it before either command tells Maven to delete the target/ directory first, ensuring a fresh build.

What mvn clean package Does

mvn clean package

This command performs the following steps in order:

1. clean - Deletes the target/ directory and all previously built files.
2. validate - Checks that the POM is well-formed and all required information is available.
3. compile - Compiles the Java source files in src/main/java into bytecode in target/classes.
4. test - Runs unit tests from src/test/java. If any test fails, the build stops.
5. package - Bundles the compiled classes and resources into a distributable format (JAR, WAR, EAR) and places the artifact in target/.

After this command completes, the artifact exists only inside the project's own target/ directory. No other project can reference it as a Maven dependency.

What mvn clean install Does

mvn clean install

This command runs every phase that package runs, plus two additional phases:

1. verify - Runs integration tests and checks to ensure quality criteria are met.
2. install - Copies the packaged artifact and its POM into the local Maven repository at ~/.m2/repository.

After this command completes, any other Maven project on the same machine can declare this artifact as a <dependency> and Maven will resolve it from the local repository without needing a remote fetch.

1<!-- In another project's pom.xml -->
2<dependency>
3    <groupId>com.example</groupId>
4    <artifactId>shared-utils</artifactId>
5    <version>1.0.0-SNAPSHOT</version>
6</dependency>

Side-by-Side Comparison

When to Use Each Command

Use mvn clean package when:

• You are building a standalone application that does not serve as a dependency for other projects.
• You are running builds in CI/CD pipelines where the artifact is uploaded to a remote repository via mvn deploy instead.
• You want a fast feedback loop during development and do not need the artifact in your local repository.
• You are building a Docker image or deployment package from the JAR in target/ directly.

# CI pipeline example: package, then deploy to Nexus
mvn clean package -DskipTests
mvn deploy -DskipTests

Use mvn clean install when:

• You are working on a multi-module project where child modules depend on sibling modules.
• You are developing a shared library that other local projects reference as a dependency.
• You need the artifact in ~/.m2/repository for local testing before publishing to a remote repository.

1# Install shared library, then build the consuming project
2cd ~/projects/shared-utils
3mvn clean install
4
5cd ~/projects/main-app
6mvn clean package

Multi-Module Projects: Where install Matters Most

In a multi-module Maven project, modules often depend on each other. Consider this structure:

1parent-project/
2  pom.xml
3  core-module/
4    pom.xml
5  api-module/        (depends on core-module)
6    pom.xml
7  web-module/        (depends on api-module)
8    pom.xml

When you run mvn clean install from the parent, Maven builds each module in dependency order and installs each artifact into the local repository. This means api-module can resolve core-module as a dependency during compilation.

If you run mvn clean package from the parent, Maven uses the reactor to resolve inter-module dependencies within the same build session. This works for a full build from the parent, but fails if you later try to build api-module independently:

1# This works (reactor resolves dependencies)
2cd parent-project
3mvn clean package
4
5# This fails if core-module is not in ~/.m2/repository
6cd parent-project/api-module
7mvn clean package
8# ERROR: Could not find artifact com.example:core-module:jar:1.0.0-SNAPSHOT

Running mvn clean install from the parent first avoids this problem.

Skipping Tests for Faster Iteration

Both commands run the full test suite by default. During rapid development, you may want to skip tests temporarily:

1# Skip test compilation and execution
2mvn clean package -DskipTests
3
4# Skip test execution but still compile test classes
5mvn clean install -Dmaven.test.skip=false -DskipTests
6
7# Skip everything including test compilation
8mvn clean package -Dmaven.test.skip=true

Use -DskipTests sparingly. It speeds up builds but hides regressions.

Common Pitfalls

Running install on every build. Developers sometimes default to mvn clean install out of habit, even for standalone applications. This pollutes ~/.m2/repository with intermediate SNAPSHOT versions and can cause stale artifact issues when switching between branches.

Forgetting clean entirely. Running mvn package without clean can produce artifacts that contain stale class files from a previous compilation. Always include clean unless you are sure the incremental build is correct.

Confusing install with deploy. The install phase copies the artifact to your local machine only. To publish to a shared repository like Nexus or Artifactory, use mvn deploy. These are different lifecycle phases with different purposes.

Building a single module without installing its dependencies first. In a multi-module project, building one module in isolation requires that its sibling dependencies exist in the local repository. Either run install from the parent first, or use the -pl and -am flags to build the module with its dependencies.

# Build api-module and all modules it depends on
mvn clean install -pl api-module -am

Assuming package runs integration tests. The verify phase, where integration tests typically execute via the Failsafe plugin, runs after package but before install. If you want integration tests without installing, use mvn clean verify explicitly.

Summary

• mvn clean package builds and tests your project, producing an artifact in target/. It does not modify your local Maven repository.
• mvn clean install does everything package does, plus copies the artifact to ~/.m2/repository for use by other local projects.
• Use package for standalone builds, CI pipelines, and fast iteration. Use install for multi-module projects and shared libraries.
• In multi-module projects, install is usually necessary so that sibling modules can resolve each other as dependencies when built independently.
• Neither command publishes to a remote repository. That is the job of mvn deploy.