Build Lifecycle

Maven is not just a dependency downloader. Its real power comes from a structured build lifecycle that turns raw source code into tested, packaged, and deployable artifacts. This chapter explains how that lifecycle works and which commands you will use every day.

Prerequisites

• A Maven project ready to build
• Basic familiarity with pom.xml

The Three Built-in Lifecycles

Maven defines three independent lifecycles. Each lifecycle is a sequence of phases, and each phase represents a stage in the build process.

You run a lifecycle by naming one of its phases on the command line. Maven executes that phase and every phase before it in the same lifecycle.

The Default Lifecycle Phases

The default lifecycle is the one you interact with most. Here are the key phases in order:

The Clean Lifecycle

The clean lifecycle has three phases, but you typically only use the first:

Running mvn clean wipes the target/ folder, giving you a fresh start. This is useful when you suspect stale compiled classes are causing strange behavior.

The Site Lifecycle

The site lifecycle generates project documentation:

In modern projects, this lifecycle is less commonly used because documentation usually lives in README files, wikis, or dedicated documentation platforms. Still, it is available when you need it.

Phases, Plugins, and Goals

A phase is a step in a lifecycle. A goal is a specific task provided by a plugin. Maven binds goals to phases so that when a phase runs, its associated goals execute automatically.

For example, the compile phase is bound to the compile goal of the maven-compiler-plugin. You do not need to configure this binding for standard phases — it is part of Maven's Super POM.

You can also run a goal directly without going through a lifecycle phase:

# Run the dependency:tree goal directly
mvn dependency:tree

Here, dependency is the plugin prefix and tree is the goal. This does not trigger any lifecycle phase.

Essential Build Commands

Compiling

# Compile main sources to target/classes
mvn compile

This is the fastest way to check whether your code compiles. It does not run tests or package anything.

Testing

# Compile and run all unit tests
mvn test

If any test fails, the build stops immediately. Failed tests are reported in target/surefire-reports/.

Packaging

# Compile, test, and package the artifact
mvn package

The output appears in target/. The file extension depends on your <packaging> element — usually .jar.

Installing Locally

# Package and copy the artifact to the local repository
mvn install

This makes the artifact available to other projects on your machine. Without install, a multi-module project cannot resolve its own sub-modules as dependencies.

Deploying to a Remote Repository

# Install and publish to a remote repository
mvn deploy

This requires <distributionManagement> configured in your POM and authentication set up in settings.xml. We will cover publishing in the Repositories chapter.

Combining Commands

# Clean first, then package
mvn clean package

When you list multiple goals or phases, Maven executes them in order. clean runs first, deleting target/, then the default lifecycle runs up to package.

Another common combination:

# Skip tests and build fast
mvn clean package -DskipTests

Skipping Tests

The -DskipTests flag tells Maven to bypass the test execution phase while still compiling the test sources. This is useful during rapid development when you want a quick packaging cycle.

# Package without running tests
mvn package -DskipTests

If you want to skip both test execution and test compilation, use:

# Skip tests entirely (faster, but riskier)
mvn package -Dmaven.test.skip=true

Activating Profiles

Profiles let you define environment-specific configurations inside pom.xml. You activate a profile with the -P flag:

# Activate the 'production' profile
mvn package -Pproduction

If a profile is active, its properties, dependencies, and plugin configurations override or extend the base configuration. We will explore profiles in depth in the Resources and Configuration chapter.

Parallel Builds

On multi-core machines, you can speed up multi-module builds by compiling modules in parallel:

# Use 4 threads for the build
mvn clean package -T 4

Or let Maven guess based on your CPU cores:

# One thread per CPU core
mvn clean package -T 1C

Single-module projects see little benefit, but large multi-module builds can be significantly faster.

FAQ

What is the difference between mvn install and mvn package?

package creates the artifact in target/. install does everything package does, then copies the artifact into your local Maven repository (~/.m2/repository). Other projects on your machine can only reference your artifact as a dependency after install.

Can I run a single test instead of all of them?

Yes:

# Run a single test class
mvn test -Dtest=MyTest
 
# Run a single test method
mvn test -Dtest=MyTest#myMethod

Why does mvn clean sometimes fail with "unable to delete"?

Another process — such as a running application, an IDE indexer, or a file explorer — may be holding files inside target/. Close any running Java processes and retry.

What does mvn verify do that mvn test does not?

verify runs integration tests and additional quality checks configured by plugins (such as code coverage or static analysis). test only runs unit tests. In CI pipelines, mvn verify is the standard target for a complete build.

Is there a way to see what plugins and goals will run without actually executing them?

Yes. This command prints the execution plan:

# Dry-run the package phase
mvn package --dry-run

It lists every goal that would execute, which is helpful for debugging unexpected plugin behavior.