How to Install Spring Boot: From an Empty Folder to a Running App

by Souy Soeng /October 26, 2026

Terminal showing a Spring Boot app starting with Tomcat on port 8080, beside the Spring Initializr web page

To install Spring Boot, you install a Java Development Kit (JDK), generate a project with Spring Initializr, open it in your IDE, and start it with a single wrapper command. You don't install Spring Boot as a separate program. It arrives as libraries inside the project that Initializr builds for you.

Writing the code is rarely the hard part for beginners. Getting from an empty folder to a server that actually starts is. This guide follows that path in order. It explains why each step matters and what to check before you move on. At the end, you'll have a web app answering on localhost:8080 and a first endpoint of your own.

In short

Spring Boot 3 needs Java 17 or later, so confirm your JDK version and JAVA_HOME first.
Generate the project on start.spring.io with a stable release and the Spring Web dependency.
Open the folder that contains pom.xml, then wait for dependencies to download.
Start the app with ./mvnw spring-boot:run (or ./gradlew bootRun) and check localhost:8080.
A 404 Whitelabel page at this point means the server is working.

Check what you need before you start

The goal is a Spring Boot web app running on your own machine and answering at localhost, port 8080. You only need a few things to get there. Check them now, because finding a missing tool halfway through a step is far more frustrating than sorting it out first.

Java 17 is the firm requirement. Spring Boot 3 uses Java 17 as its minimum. On Java 8 or 11, the build fails before your app even starts. The other tools are flexible. IntelliJ IDEA understands Spring projects out of the box. VS Code works well once you add the Java extension pack.

Java 17 or later
A terminal: Terminal on macOS, PowerShell on Windows, or any Linux shell
An IDE such as IntelliJ IDEA or VS Code
Basic Java knowledge, so classes and annotations look familiar

Install a JDK and confirm Java 17 is found

Spring Boot runs on the JVM, so you need a full JDK, not just a Java runtime. Install one, for example Eclipse Temurin, through an installer or your package manager. Installing is the easy half. Confirming the installation matters more, because many build errors come from the wrong Java version being picked up.

Open a new terminal and run java -version. Only the first number matters: 17, 21 or anything newer is fine. If you see 1.8 or 11, an older JDK is still first on your PATH. Next, run echo $JAVA_HOME. It should print the folder of that same JDK.

If JAVA_HOME prints nothing, set it. Maven, Gradle and your IDE often read this variable instead of the PATH. If it is missing or points to an old JDK, your terminal and your build tool can end up using different versions of Java.

java -version shows major version 17 or higher
echo $JAVA_HOME prints the same JDK's folder
You opened a new terminal after installing

java -version
echo $JAVA_HOME

Generate the project on Spring Initializr

Don't write the project skeleton by hand. Spring Initializr at start.spring.io is the official project generator, and it builds a correct structure in seconds. The settings you pick here shape the whole project, so take a moment over them now to avoid restructuring later.

Under Project, choose Maven or Gradle. Both work, so use the one your team already uses. Maven is configured with an XML file called pom.xml. Gradle uses a script and is often faster on large builds. Both include a wrapper script, so you don't need to install either tool. Set Language to Java. Then choose the newest stable Spring Boot release, not a SNAPSHOT or milestone build. Those are previews that can change.

Set Group to com.example (or your own domain, reversed) and Artifact to demo. Together they form the project's identity and become its package name and jar file name. Click Add Dependencies, search for "web" and tick Spring Web. It adds Spring MVC for handling requests plus an embedded Tomcat server, so there's no separate server to install. Press Generate to download demo.zip.

Build tool chosen: Maven or Gradle
Language set to Java
A stable Spring Boot release, with no SNAPSHOT or milestone label
Spring Web added as a dependency
demo.zip downloaded and saved somewhere sensible

Unzip and open the project in your IDE

Move the zip into your projects folder and run unzip demo.zip. Change into the demo folder and list its contents. You should see mvnw (the Maven wrapper), mvnw.cmd for Windows, pom.xml, HELP.md and the src folder. Running code . opens the folder in VS Code.

Open the folder itself, the one that contains pom.xml or build.gradle. Don't open the zip or a parent folder. Your IDE reads the build file to recognise a Spring project. If it can't see that file, the IDE treats the folder as plain files.

Expect a short wait the first time. Your machine downloads the Spring libraries from the internet while the IDE indexes the project. Watch the progress bar at the bottom of the IDE. Once the red underlines disappear, you're ready to run the app.

The folder you opened contains pom.xml or build.gradle
Indexing and dependency downloads have finished
No red underlines remain in the source files

unzip demo.zip
cd demo && ls
code .

Run Spring Boot from the terminal

Use the terminal rather than an IDE run button, because the command behaves the same on every machine. The wrapper downloads the correct Maven or Gradle version by itself. That's why this works even if you've never installed either tool.

From inside the demo folder, run ./mvnw spring-boot:run. Maven builds the project, prints the Spring Boot banner, and initialises Tomcat on port 8080. Two final lines confirm that Tomcat started and DemoApplication started. Gradle users run ./gradlew bootRun instead, and the log looks very similar. On Windows, leave off the ./ and use mvnw.cmd or gradlew.bat.

Leave the server running. It stays in the foreground, so that terminal is now busy serving requests. Press Ctrl+C when you want to stop it.

The Spring Boot banner appears in the log
The log shows "Tomcat started on port 8080"
The log shows "Started DemoApplication"

./mvnw spring-boot:run

Confirm Tomcat is answering on port 8080

A log line tells you the app expects to work. A response from the server proves it does. Start with the log. The line "Tomcat started on port 8080" means the embedded server is listening on that port. If the line is missing, something failed earlier, and the error is printed above where it should be.

Next, visit localhost:8080 in your browser. You'll get a 404 Whitelabel error page. Then open a second terminal and run curl localhost:8080. This time the 404 comes back as JSON. Both responses come from your running app.

A 404 is the expected result here. No controller is mapped to that path yet, so Spring correctly reports "not found". It is still a real response, and it shows the server is working.

The browser shows a Whitelabel 404 page
curl returns a JSON 404 error
Neither request fails with a connection error

Fix common Spring Boot startup errors

Most first-run failures come from a short list of causes, and each has a quick fix. Find the error message in your terminal, match it to a cause below, apply the fix, and run the command again.

Read the first error, not the last one. Spring prints long stack traces, and the line that names the real cause is usually near the top. Fix that error first, because the errors after it usually disappear too.

Port 8080 already in use: stop the other app, or set server.port to a different number
Build rejects your Java release: upgrade to Java 17 or later
Build uses an older JDK: point JAVA_HOME at your JDK 17+ install
Permission denied on mvnw: run chmod +x mvnw

Add your first endpoint

Once the app runs cleanly, replace the 404 with a real response. Create a class next to DemoApplication and annotate it with @RestController. Inside it, add a method with @GetMapping("/"). This maps the root path to that method. The method returns a string, and Spring sends that string as the response body.

To test it, press Ctrl+C, run the wrapper command again and refresh localhost:8080. The Whitelabel page is replaced by your greeting. Spring Boot DevTools can do this restart for you automatically.

If port 8080 is often taken on your machine, change the port permanently. Open application.properties in src/main/resources and add server.port=8081. Your app will then start on that port every time.

The new class is in the same package as DemoApplication
The app was restarted after adding the class
localhost:8080 now returns your text instead of a 404

@RestController
class HelloController {
  @GetMapping("/")
  String hello() { return "Hello!"; }
}

Key takeaways

Install JDK 17 or later and confirm JAVA_HOME before anything else.
Generate the project on start.spring.io with a stable release and Spring Web.
Open the folder containing pom.xml and let dependencies finish downloading.
Run with ./mvnw spring-boot:run or ./gradlew bootRun. No separate Maven, Gradle or Tomcat install is needed.
Check that localhost:8080 responds. At first, even a 404 means success.
If something breaks, go back through the steps in order and read the first error in the log.

Frequently asked questions

Do I need to install Spring Boot separately?

No. Spring Boot comes as libraries in the project that Spring Initializr generates. The build tool downloads them when you first open or run the project, so you only need to install a JDK and an IDE.

Which Java version does Spring Boot 3 need?

Spring Boot 3 requires Java 17 as its minimum, and newer versions such as 21 also work. On Java 8 or 11, the build fails before the app starts.

Do I have to install Maven or Gradle?

No. Projects from Spring Initializr include a wrapper script (mvnw or gradlew). It downloads the correct build tool version for you, so the run command works even if you've never installed Maven or Gradle.

Why do I get a 404 Whitelabel error page at localhost:8080?

A new project has no controller mapped to the root path, so Spring correctly answers "not found". The 404 is still a real response from the server, which confirms the app is running.

What should I do if port 8080 is already in use?

Stop the other application that holds the port, or choose a different one. Add server.port=8081 to application.properties in src/main/resources to change the port permanently.

Should I choose Maven or Gradle for a new Spring Boot project?

Both work well, so pick the one your team already uses. Maven is configured with an XML file called pom.xml, and Gradle uses a script and is often faster on large builds.

Watch the full video on YouTube →

Tag

Ad