Installing OpenJDK 21 on Debian 12: 'java' command not found

The 'java' command not found error on Debian 12 usually occurs because the default JRE package is not installed or the binary path is missing from your system's environment variables. Installing the openjdk-21-jre-headless package and verifying the installation via update-alternatives typically resolves this issue immediately, ensuring that the java executable is correctly linked and accessible in your terminal.

Understanding the Default Java Packages on Debian 12

Debian 12 (Bookworm) manages multiple versions of Java through a sophisticated alternative system. Unlike some older distributions that might link java to a specific version by default, Debian allows administrators to choose which version is active for the generic java, javac, and keytool commands. If you have never explicitly installed a Java Runtime Environment (JRE), the java command will simply not exist in your PATH. It is important to distinguish between the JRE and the JDK. The JRE contains only what is needed to run Java applications, while the JDK includes tools like the compiler (javac) and debugger required for development. For most users who only need to execute .jar files or run server-side applications, the Headless JRE is sufficient and lighter on system resources. However, if you are developing software, you must install the full JDK package. When you encounter the "command not found" error, it confirms that no Java binaries are currently registered in your system's search paths. This is a clean state, meaning there are no conflicting installations or broken symlinks causing the issue. You can proceed with a fresh installation without needing to uninstall previous versions first.

Installing OpenJDK 21 on Debian 12

To resolve the immediate error, you need to install the appropriate package using the Advanced Package Tool (APT). Open your terminal and update your package list to ensure you are pulling the latest metadata from the Debian repositories.

sudo apt update

Next, install the OpenJDK 21 JRE. This package provides the runtime environment necessary to execute Java programs.

sudo apt install openjdk-21-jre-headless

If you require development tools such as compilation capabilities, install the full JDK instead:

sudo apt install openjdk-21-jdk

Once the installation completes, the binary files are placed in /usr/lib/jvm/java-21-openjdk-amd64/bin/. However, Debian does not automatically add this directory to your global PATH variable in all configurations, nor does it always set up the alternatives links immediately. You may still see the "command not found" error until you verify the alternative configuration.

Verifying and Configuring Alternatives

Debian uses update-alternatives to manage symbolic links for commands that have multiple implementations. Even after installing the package, you should verify that java points to the correct executable. Run the following command to check the current status:

update-alternatives --query java

If the output indicates that the alternatives are not configured or points to an incorrect version, you can manually configure them. To set OpenJDK 21 as the default, use:

sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java

Repeat this process for other common Java commands like javac and keytool if you installed the full JDK. After setting the alternatives, verify the installation by running:

java -version

You should see output confirming OpenJDK 21 is now active. If you still face issues, ensure that /usr/lib/jvm/java-21-openjdk-amd64/bin is included in your PATH environment variable by checking echo $PATH.

Troubleshooting Persistent Issues

In rare cases, package conflicts or partial upgrades can leave the system in an inconsistent state. If apt reports errors during installation, consult our guide on Fixing E: Sub-process /usr/bin/dpkg returned an error code (1) on Kali Linux, as the troubleshooting steps for dpkg errors are largely applicable across Debian-based systems. Another common pitfall is shell caching. If you recently installed Java but your terminal session started before the installation completed, your shell might still cache the old state where java was not found. Simply closing and reopening your terminal emulator or running hash -r in bash will clear the command cache and force the shell to re-evaluate the PATH. For users managing complex application deployments, ensuring Java is available at startup is crucial. While this article focuses on manual installation, automated deployment tools often handle these dependencies. For insights into making applications run reliably at startup, you might find our article on Making a Debian Linux Application Run at Startup with InstallBuilder useful for understanding service management contexts.

Frequently Asked Questions

Why does 'java -version' show a different version than what I installed?

This happens when multiple Java versions are installed and update-alternatives is pointing to an older one. You must explicitly set the default using sudo update-alternatives --set java /path/to/openjdk-21/bin/java to override the existing configuration.

Is it safe to remove OpenJDK 17 after installing OpenJDK 21?

Yes, it is safe to remove older versions if you are certain no legacy applications depend on them. You can remove them with sudo apt remove openjdk-17-jre-headless, but be aware that removing the last installed JRE will break any scripts relying on the java command until a new one is installed.

How do I set JAVA_HOME for OpenJDK 21?

You can determine the home directory by running readlink -f $(which java) | sed "s:/bin/java::". Add this path to your ~/.bashrc or /etc/environment file as export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 to ensure build tools like Maven or Gradle can locate it.

What if I get a 'permission denied' error when running java?

This is unusual for standard installations and suggests the binary lacks execute permissions or is corrupted. Reinstall the package using sudo apt reinstall openjdk-21-jre-headless to restore correct permissions and file integrity provided by the Debian package manager.

Can I use OpenJDK 21 for Android development?

Android Studio typically bundles its own JDK, but if you need to specify a system JDK, OpenJDK 21 is supported by modern Android build tools. Ensure you install the full openjdk-21-jdk package rather than just the headless JRE, as the Android SDK requires compilation tools.