How to Switch Between Java Versions on Linux

In this tutorial, you'll learn about How to Switch Between Java Versions on Linux. We cover key concepts, practical examples, and best practices.

The Problem

Your system has multiple Java versions installed, and a project requires a specific one. Running java -version shows the wrong version, or builds fail with "invalid source release" errors.

Quick Fix

Step 1: List installed Java versions

sudo update-alternatives --config java

Expected:

There are 3 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                            Priority   Status
------------------------------------------------------------
* 0            /usr/lib/jvm/java-11-openjdk-amd64/bin/java      1111      auto mode
  1            /usr/lib/jvm/java-11-openjdk-amd64/bin/java      1111      manual mode
  2            /usr/lib/jvm/java-17-openjdk-amd64/bin/java      1711      manual mode
  3            /usr/lib/jvm/java-21-openjdk-amd64/bin/java      2111      manual mode

Step 2: Switch the default Java version

sudo update-alternatives --config java

Enter the selection number for the desired Java version (e.g., 2 for Java 17).

Step 3: Verify the switch

java -version

Expected:

openjdk version "17.0.10" 2024-01-16
OpenJDK Runtime Environment (build 17.0.10+7-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.10+7-Ubuntu, mixed mode)

Step 4: Set JAVA_HOME environment variable

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

Add these lines to ~/.bashrc or ~/.zshrc for persistence.

Step 5: Switch javac as well

sudo update-alternatives --config javac

Some tools use javac directly. Keep it in sync with the java version.

Step 6: Per-project version with SDKMAN

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 21.0.2-open
sdk use java 21.0.2-open

SDKMAN manages per-shell and per-project Java versions without system-wide changes.

Step 7: List all available JDK versions

sudo update-alternatives --list java

Expected:

/usr/lib/jvm/java-11-openjdk-amd64/bin/java
/usr/lib/jvm/java-17-openjdk-amd64/bin/java
/usr/lib/jvm/java-21-openjdk-amd64/bin/java

Step 8: Switch version for a single command

JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 ./gradlew build

This overrides JAVA_HOME for only this command without affecting the session.

Alternative Solutions

Install a specific JDK via apt:

sudo apt install openjdk-21-jdk -y

Common Errors

update-alternatives does not switch all Java tools: java and javac are separate alternatives. Run sudo update-alternatives --config java and sudo update-alternatives --config javac separately.

JAVA_HOME still points to old version: Even after update-alternatives, JAVA_HOME may still point to the old JDK. Update it in ~/.bashrc and restart the terminal.

SDKMAN not found after install: Run source "$HOME/.sdkman/bin/sdkman-init.sh" or restart the terminal after installing SDKMAN.

Build tool uses the wrong Java: Maven and Gradle use JAVA_HOME by default. If java -version shows Java 21 but Maven uses Java 11, check that JAVA_HOME is set correctly.

IntelliJ IDEA ignores system Java: IntelliJ has its own JDK configuration. Go to File > Project Structure > SDK and set the desired JDK path manually.

Docker containers have different Java: If your app runs in Docker, the container uses its own JDK. Update the base image or set JAVA_HOME in the Dockerfile.

Prevention

• Use SDKMAN for per-project Java version management.
• Keep at least two LTS versions installed for testing backward compatibility.
• Set JAVA_HOME in CI/CD pipeline variables, not in the build script.
• Document the required Java version in the project README.