Introduction

An executable Spring Boot JAR is a packaged application that includes your app classes and the runtime dependencies needed to start it directly with java -jar. With Gradle, the normal way to build that artifact is to apply the Spring Boot plugin and run the bootJar task.

Use the Spring Boot Gradle Plugin

The plugin creates the executable archive and wires the classpath correctly. A minimal build.gradle using the Groovy DSL looks like this:

1plugins {
2    id 'java'
3    id 'org.springframework.boot' version '4.0.3'
4}
5
6group = 'com.example'
7version = '0.0.1-SNAPSHOT'
8
9java {
10    toolchain {
11        languageVersion = JavaLanguageVersion.of(17)
12    }
13}
14
15repositories {
16    mavenCentral()
17}
18
19dependencies {
20    implementation 'org.springframework.boot:spring-boot-starter-web'
21    testImplementation 'org.springframework.boot:spring-boot-starter-test'
22}
23
24tasks.named('test') {
25    useJUnitPlatform()
26}

That is enough for a basic web app. The important plugin is org.springframework.boot, because it adds the packaging behavior that creates the runnable archive.

Build the Executable JAR

From the project root, run:

./gradlew bootJar

On Windows:

.\gradlew.bat bootJar

The built file usually appears in:

build/libs/

You can then run it directly:

java -jar build/libs/demo-0.0.1-SNAPSHOT.jar

If the app starts, the JAR is truly executable in the Spring Boot sense.

Know the Difference Between jar and bootJar

This is the part that trips people up. Gradle's standard jar task creates a plain JAR of your compiled classes. That is not the same thing as a Spring Boot executable archive.

Spring Boot's bootJar task creates a layered archive with your app plus its dependencies arranged so the Spring Boot launcher can start it.

In other words:

• 'jar builds a plain Java archive'
• 'bootJar builds the runnable Spring Boot archive'

For most Boot applications, bootJar is the task you actually want.

Main Class Detection

Spring Boot normally detects your application entry point automatically if you have a standard main method:

1package com.example;
2
3import org.springframework.boot.SpringApplication;
4import org.springframework.boot.autoconfigure.SpringBootApplication;
5
6@SpringBootApplication
7public class DemoApplication {
8    public static void main(String[] args) {
9        SpringApplication.run(DemoApplication.class, args);
10    }
11}

If Gradle cannot determine the main class, you can configure it explicitly:

springBoot {
    mainClass = 'com.example.DemoApplication'
}

That removes ambiguity in multi-module or unusual project layouts.

After the build, it is also worth inspecting build/libs directly so you know which archive name your CI or deployment script should pick up. That small habit prevents "build succeeded but deploy script used the wrong file" errors.

When You Also Need a Plain JAR

Sometimes you want both archives, for example if another system expects a plain library JAR. In that case you can keep jar enabled and customize names separately.

tasks.named('jar') {
    enabled = true
}

Most standalone Boot services do not need that, but it is useful to know the distinction rather than assuming all JAR tasks are interchangeable.

Common Pitfalls

• Running gradle jar and expecting a fully executable Spring Boot archive.
• Forgetting the Spring Boot Gradle plugin, which means bootJar is not available.
• Building successfully but not testing the artifact with java -jar.
• Misconfigured main-class detection in nonstandard project layouts.
• Mixing old plugin examples with current Spring Boot versions without checking the plugin syntax and Java baseline.

Summary

• To build a runnable Spring Boot JAR with Gradle, apply the Spring Boot plugin and run bootJar.
• The executable artifact is usually written under build/libs.
• 'bootJar is different from the plain jar task.'
• A standard main method is usually detected automatically, but you can configure it explicitly if needed.
• Always verify the result by starting it with java -jar, not just by trusting that the build succeeded.