Spring Framework Tutorial

Installing the JDK on Windows, macOS and Linux

Every Spring application needs a JDK (Java Development Kit). Spring Boot 4.1 requires Java 17 as a minimum and runs on newer releases, so any LTS version from 17 upward works. For a new machine we recommend Java 21 or Java 25 because they are long-term-support releases that stay maintained for years.

This lesson gives step-by-step instructions for Windows, macOS and Linux, shows how to set JAVA_HOME correctly, and explains the mistakes that cause most "Java is not found" problems.

Choosing a JDK distribution and version

Java is open source, and several vendors publish free, compatible builds of the same OpenJDK code. Eclipse Temurin (from the Adoptium project) is a popular neutral choice, and Oracle JDK, Amazon Corretto, Microsoft Build of OpenJDK and Azul Zulu are also widely used. For learning Spring they behave the same.

Pick an LTS version: 17, 21 or 25. If your team or employer already uses one, match it. Whatever you choose, the version must be at least the value of java.version in your project (Spring Initializr generates it for you), otherwise the compiler stops with an error such as "release version 21 not supported".

You need a JDK, not just a JRE. The JDK contains javac, the compiler that Maven and Gradle call.

Windows

The easiest route is the Windows package manager. Open PowerShell and run one of the following (the package IDs below exist in the winget catalogue for Temurin 17 and 21):

Install Temurin 21: winget install EclipseAdoptium.Temurin.21.JDK
Install Temurin 17: winget install EclipseAdoptium.Temurin.17.JDK
For other versions (for example 25), download the MSI installer from adoptium.net and run it. In the installer, choose the options that add Java to PATH and set JAVA_HOME.
Close and reopen your terminal, then verify with java -version and javac -version.

macOS

If you use Homebrew, install Temurin as a cask. Otherwise download the .pkg installer from adoptium.net.

Install with Homebrew: brew install --cask temurin@21
List installed JDKs: /usr/libexec/java_home -V
Use a specific one in the current shell: export JAVA_HOME=$(/usr/libexec/java_home -v 21)
Make it permanent by adding that export line to your ~/.zshrc.

Linux

Use your distribution's package manager, or SDKMAN if you want to switch versions easily.

Ubuntu / Debian: sudo apt update && sudo apt install openjdk-21-jdk
Fedora / RHEL family: sudo dnf install java-21-openjdk-devel
Find the install folder: readlink -f $(which javac) (JAVA_HOME is the folder above bin).
Add export JAVA_HOME=/path/to/jdk to ~/.bashrc or ~/.zshrc, then run source ~/.bashrc.

SDKMAN: one tool for every OS-like environment

SDKMAN works on macOS, Linux and Windows through WSL or Git Bash. It installs several JDKs side by side and switches between them with one command, which is handy when different projects need different Java versions.

Install SDKMAN: curl -s "https://get.sdkman.io" | bash then open a new terminal.
See available versions: sdk list java
Install one using the identifier shown in the list, for example sdk install java 21.0.x-tem (replace with a real identifier from the list).
Switch for the current terminal: sdk use java 21.0.x-tem, or set a default with sdk default java 21.0.x-tem.

Setting JAVA_HOME and PATH

Maven, Gradle and many IDE plugins read the JAVA_HOME environment variable to find your JDK. It must point to the JDK's root folder (the folder that contains bin, lib and conf), not to the bin folder and not to the java.exe file.

On Windows, set it from PowerShell for your user account, then open a new terminal: setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-21.0.x.x-hotspot" (use the real folder name on your machine). You can also use the Environment Variables dialog: Start menu, search "Edit the system environment variables", then Environment Variables.

On macOS and Linux use an export line in your shell profile, as shown above. Finally make sure the JDK's bin folder is on PATH (on Windows add %JAVA_HOME%\bin; on macOS and Linux add $JAVA_HOME/bin).

Verifying the installation

Open a brand-new terminal, because old terminals keep the old environment, and run the checks in the example below. Both java and javac should report the same major version. On Windows you can also run where java to see which java.exe is found first. If that list shows an older Java ahead of your new one, fix the PATH order.

Examples

Verify the JDK and JAVA_HOME (macOS / Linux shell)

Java

java -version
javac -version
echo $JAVA_HOME
$JAVA_HOME/bin/java -version

Output

openjdk version "21.0.x" 2025-xx-xx LTS
OpenJDK Runtime Environment Temurin-21.0.x+x (build 21.0.x+x-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.x+x (build 21.0.x+x-LTS, mixed mode, sharing)
javac 21.0.x
/usr/lib/jvm/temurin-21-jdk
openjdk version "21.0.x" 2025-xx-xx LTS

Verify on Windows PowerShell

Java

java -version
javac -version
echo $env:JAVA_HOME
where.exe java

Output

java version "17.0.12" 2024-07-16 LTS
Java(TM) SE Runtime Environment (build 17.0.12+8-LTS-286)
javac 17.0.12
C:\Program Files\Java\jdk-17
C:\Program Files\Common Files\Oracle\Java\javapath\java.exe

Common Mistakes

Installing only a JRE. Maven and Gradle need javac, which only a JDK provides.
Pointing JAVA_HOME at the bin folder or at a path with the wrong folder name. A wrong value makes the Maven wrapper fail with: The JAVA_HOME environment variable is not defined correctly.
On Windows, copying the java.exe path from "where java" into JAVA_HOME. That path is often a small launcher shim under Common Files\Oracle\Java\javapath, not the real JDK folder. Use the folder that contains the bin directory, such as C:\Program Files\Java\jdk-17.
Testing in a terminal that was open before you changed the variables. Always open a new terminal.
Having several JDKs installed and not noticing that an older one comes first on PATH.

Key Points to Remember

Spring Boot 4.1 needs Java 17 or newer; choose an LTS such as 21 or 25.
Install a JDK (not only a JRE) from a trusted distribution such as Temurin.
JAVA_HOME points to the JDK root folder; PATH must include its bin folder.
Verify with java -version, javac -version and where java (Windows) or which java (macOS/Linux).

Practice the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

Use your local JDK or project IDE for these examples. Codelab currently runs Python and HTML/CSS/JavaScript; framework examples may need project dependencies.