Spring Boot provides a Maven plugin called spring-boot-maven-plugin. Its goal prefix is spring-boot, so we call its goals like this: spring-boot:<goal-name>.
These two goals are used most often:
- spring-boot:run to run our Spring Boot application directly from the compiled classes (no jar file is needed).
- spring-boot:repackage to turn a normal jar or war file into an executable jar or war file.
The plugin has a few more goals. For example, build-image creates a container image, build-info creates a build-info.properties file, start and stop are used in integration tests, process-aot is used for ahead-of-time processing (for example, for GraalVM native images).
Using Gradle instead of Maven? See the Spring Boot Gradle Plugin Tutorial.
Let's explore the plugin with an example.
Example
Adding the plugin in pom.xml
pom.xml<project .....> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>4.1.2</version> <relativePath></relativePath> </parent> <groupId>com.logicbig.example</groupId> <artifactId>boot-mvn-plugin-example</artifactId> <version>1.0-SNAPSHOT</version> <properties> <java.version>25</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <mainClass>com.logicbig.example.MainClass</mainClass> </configuration> </plugin> </plugins> </build> </project>
We do not need a <version> for the plugin. The spring-boot-starter-parent already manages it, so the plugin always has the same version as Spring Boot.
Listing the goals
Let's run mvn spring-boot:help at the location where we created our pom.xml. Maven finds the plugin version in our project (the parent pom manages it), so we see the goals of exactly the plugin version we use:
Output (filtered)$ mvn spring-boot:help Spring Boot Maven Plugin
This plugin has 3 goals:
spring-boot:help Display help information on spring-boot-maven-plugin. Call mvn spring-boot:help -Ddetail=true -Dgoal=<goal-name> to display parameter details.
spring-boot:repackage Repackages existing JAR and WAR archives so that they can be executed from the command line using java -jar. With layout=NONE can also be used simply to package a JAR with nested dependencies (and no main class, so not executable).
spring-boot:run Run an executable archive application.
To see the parameters of the goals, we add -Ddetail=true. We can show a single goal with -Dgoal=run.
We can also use mvn help:describe. But this command does not read the plugin version from our pom. If we write -Dplugin=spring-boot or -Dplugin=org.springframework.boot:spring-boot-maven-plugin, Maven may show the newest version it can find (even a milestone version), and not the version our project uses. To describe an exact version we add it to the coordinates, for example -Dplugin=org.springframework.boot:spring-boot-maven-plugin:4.1.1.
Version note: the Spring Boot 1.2.0 plugin had only 3 goals: help, repackage and run. The goals build-info, start and stop were added later, so the 1.4.2 plugin had 6 goals. All of these goals still exist today. The five newer goals are build-image and build-image-no-fork (added in 2.3), process-aot and process-test-aot (added in 3.0), and test-run (added in 3.1).
Note: In Spring Boot 2.3.0, mvn spring-boot:help fails with "Type org.springframework.boot.maven.HelpMojo not present". After the Spring Boot build moved to Gradle, the plugin jar was published without the help class and its help data (issue #21556).
Main class
package com.logicbig.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class MainClass {
public static void main (String[] args) {
SpringApplication.run(MainClass.class, args);
}
@RestController
private static class TheController {
@RequestMapping("/")
public String handle () {
return "message from rest handler";
}
}
}
mvn spring-boot:run compiles our code and runs the application from the target/classes directory. It does not create a jar file.
D:\boot-mvn-plugin-example>mvn spring-boot:run
[INFO] Scanning for projects...
...............
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v4.1.1)
2026-10-13T10:15:02.411+08:00 INFO 12376 --- [ main] com.logicbig.example.MainClass : Starting MainClass using Java 21.0.5 with PID 12376 (D:\boot-mvn-plugin-example\target\classes started by Joe in D:\boot-mvn-plugin-example)
2026-10-13T10:15:02.414+08:00 INFO 12376 --- [ main] com.logicbig.example.MainClass : No active profile set, falling back to 1 default profile: "default"
...............
2026-10-13T10:15:03.561+08:00 INFO 12376 --- [ main] com.logicbig.example.MainClass : Started MainClass in 1.186 seconds (process running for 1.532)
By default, the embedded Tomcat server listens on port 8080. Now we can access our application in the browser at http://localhost:8080:
Output $ curl -s "http://localhost:8080" message from rest handler
We can pass options to the application like this:
mvn spring-boot:run -Dspring-boot.run.profiles=dev
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=9090
Packaging our application as an executable jar
Maven <packaging> is 'jar' by default. When we use spring-boot-starter-parent, the parent pom already binds the repackage goal to the Maven package phase. So, once the plugin is declared in our pom.xml, a simple mvn package creates the executable jar.
Output D:\boot-mvn-plugin-example>mvn clean -q package D:\boot-mvn-plugin-example>dir /s *.jar* Volume in drive D:\boot-mvn-plugin-example\target
10/14/2026 07:30 AM 12,373,103 boot-mvn-plugin-example-1.0-SNAPSHOT.jar 10/14/2026 07:30 AM 4,649 boot-mvn-plugin-example-1.0-SNAPSHOT.jar.original 2 File(s) 12,377,752 bytes
Total Files Listed: 2 File(s) 12,377,752 bytes 0 Dir(s) 24,099,221,504 bytes free
The repackage goal replaces the normal jar with an executable jar that contains our classes and all the dependency jars. The normal jar is kept with the extra extension .original.
Now we can run the jar as follows, and access the application in the browser as before:
D:\boot-mvn-plugin-example>java -jar target\boot-mvn-plugin-example-1.0-SNAPSHOT.jar
........
We can also call the goal ourselves with mvn package spring-boot:repackage, but this is not needed when the goal is already bound to the package phase. It is useful only when we want to run the goal from the command line explicitly.
Adding the repackage goal manually
If we do not use spring-boot-starter-parent (for example, we have our own parent pom), then the repackage goal is not bound automatically. In that case we add the execution ourselves, and we also have to give the plugin version:
<project ....>
......
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.1</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
After that, we just run this command to get an executable jar:
mvn package
Conflict between multiple main classes
Spring Boot automatically finds the 'main' class and runs it. If there is more than one main class, then we get the following error:
[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:4.1.1:run (default-cli) on project boot-mvn-plugin-example: Unable to find a single main class from the following candidates [com.logicbig.example.MainClass2, com.logicbig.example.MainClass] -> [Help 1]
To avoid that error we have to set the mainClass configuration:
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>com.logicbig.example.MainClass</mainClass>
</configuration>
</plugin>
Or we can use a placeholder for the mainClass. It is a good idea to give the placeholder a default value in the pom properties. Otherwise the build fails when we do not pass the value:
<properties>
<myMainClass>com.logicbig.example.MainClass</myMainClass>
</properties>
......
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>${myMainClass}</mainClass>
</configuration>
</plugin>
and then run as:
mvn spring-boot:run -DmyMainClass=com.logicbig.example.MainClass2
For the run goal there is an even simpler way. It has a built-in property, so we do not need any pom change:
mvn spring-boot:run -Dspring-boot.run.main-class=com.logicbig.example.MainClass2
Example ProjectDependencies and Technologies Used: - Spring Boot 4.1.2
Corresponding Spring Framework Version 7.0.10 Version Compatibility: 1.2.0.RELEASE - 4.1.2
- spring-boot-starter-web (Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container (deprecated in favor of spring-boot-starter-webmvc))
- JDK 25
|