Overview
For Java developers, configuring environment variables after installing the JDK (Java Development Kit) is the first step before you can start developing. Many beginners run into the issue where "JDK is installed, but typing java -version in the command line returns 'not recognized as an internal or external command.'" The root cause is almost always that environment variables are not configured or are configured incorrectly. This article provides a detailed walkthrough of Java environment variable configuration logic, step-by-step setup for multiple operating systems (Windows, Mac, Linux), verification methods, and common troubleshooting tips to help developers get their environment set up quickly.1. Why Configure Java Environment Variables?
Environment variables are parameters used by the operating system to define the runtime environment. There are two core reasons for configuring Java environment variables:
- To allow the operating system to recognize Java commands like java and javac from any directory (without having to type the full JDK installation path every time).
- To provide runtime environment dependencies for Java programs, ensuring the JVM (Java Virtual Machine) can correctly load core class libraries.
In simple terms, without configuring environment variables, the Java compiler and runtime environment cannot be "found" by the system, and any Java programs you write will fail to compile and run.
2. Preparation Before Configuration
2.1 Download and Install the JDK
First, you need to obtain the JDK installation package for your operating system. Two recommended official sources:
- Oracle JDK: Download from the official Oracle website. Requires an Oracle account to download. Suitable for commercial development (please review the license agreement).
- OpenJDK: Free and open-source. Available for download from Adoptium or the official OpenJDK website. Suitable for personal learning and non-commercial development.
2.2 Installation Notes
- The installation path should avoid containing Chinese characters, spaces, or special characters (e.g., avoid "D:\编程工具\jdk17" or "C:\Program Files\Java\jdk1.8.0_301"). Use English-only paths like "D:\jdk17" or "/Library/Java/JavaVirtualMachines/jdk17.jdk".
- Remember the JDK installation root directory — you'll need it later for environment variable configuration (e.g., "D:\jdk17" or "/usr/local/jdk17").
3. Java Environment Variable Configuration Steps by Operating System
Java environment variables typically require three parameters (some systems/versions may simplify this):
- JAVA_HOME: Points to the JDK installation root directory (the core variable that other variables depend on).
- Path: Adds the directory containing Java commands (java, javac, etc.).
- CLASSPATH: Specifies the path for loading Java class libraries (can be omitted for JDK 1.5 and above, as the default behavior automatically loads class files from the current directory).
3.1 Windows (Windows 10/11)
Windows has two types of environment variables: User Variables (apply only to the current logged-in user) and System Variables (apply to all users). System Variables are recommended.
Step 1: Open the Environment Variables Configuration Interface
- Press Win + R, type sysdm.cpl, and press Enter to open the System Properties window.
- Switch to the Advanced tab and click the Environment Variables button at the bottom.
Step 2: Configure the JAVA_HOME Variable
- In the System Variables section, click New.
- Variable name: JAVA_HOME (case-sensitive, must be all caps).
- Variable value: Paste the JDK installation root directory (e.g., "D:\jdk17" or "C:\Java\jdk1.8.0_301"). Click OK.
Step 3: Configure the Path Variable
- In the System Variables section, find the Path variable, select it, and click Edit.
- Click New and enter %JAVA_HOME%\bin (using %JAVA_HOME% references the variable you just set, avoiding hardcoded paths).
- If you have JRE installed (Java Runtime Environment), you can add another entry: %JAVA_HOME%\jre\bin (JDK 11 and above already include JRE, so this step can be skipped).
- Click Move Up to move both entries to the top (to avoid conflicts with commands from other software), then click OK to save.
Step 4: (Optional) Configure the CLASSPATH Variable
- If using JDK 1.4 or earlier, click New in the System Variables section.
- Variable name: CLASSPATH.
- Variable value: .;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar (the leading "." represents the current directory and must be included).
3.2 macOS (Intel and Apple Silicon)
On macOS, environment variables can be configured temporarily (for the current terminal session only) or permanently (for all terminal sessions). Permanent configuration is recommended.
Step 1: Find the JDK Installation Path
- Open Terminal and run the following command to get the JDK root directory (copy the output for later):
/usr/libexec/java_home -V
Example output (root directory: /Library/Java/JavaVirtualMachines/jdk17.jdk/Contents/Home):
Matching Java Virtual Machines (1):
17.0.9 (x86_64) "Oracle Corporation" - "Java SE 17.0.9" /Library/Java/JavaVirtualMachines/jdk17.jdk/Contents/Home
Step 2: Configure Environment Variables Permanently
The default shell on macOS is zsh (macOS 10.15 and later) or bash (older versions). You need to edit the appropriate config file:
- For zsh, run:
open ~/.zshrc
- For bash, run:
open ~/.bash_profile
If the file doesn't exist, create it with touch ~/.zshrc or touch ~/.bash_profile.
Add the following lines to the file (replace JDK_HOME with the actual root directory from Step 1):
# Java environment variables
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk17.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
Save and close the file. Then run the following command to apply the changes:
source ~/.zshrc # for zsh
# or
source ~/.bash_profile # for bash
3.3 Linux (Ubuntu/CentOS)
On Linux, you can also use temporary or permanent configuration. For permanent configuration, you can modify the global profile (affects all users) or the user profile (affects only the current user).
Method 1: Modify Global Profile (Recommended)
- Open Terminal and run which java to locate the JDK installation path (assuming JDK was installed via apt, yum, or manually).
Example output (symlink path): /usr/bin/java
Then use the following to find the actual root directory:
ls -l /usr/bin/java
Example output (root directory: /usr/lib/jvm/jdk17):
lrwxrwxrwx 1 root root 22 Oct 1 10:00 /usr/bin/java -> /usr/lib/jvm/jdk17/bin/java
- Open the global profile with:
sudo vi /etc/profile
- Press i to enter insert mode, and add the following at the end (replace JAVA_HOME with your actual path):
# Java environment variables
export JAVA_HOME=/usr/lib/jvm/jdk17
export PATH=$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
- Press Esc, type :wq, and press Enter to save and exit. Then run:
source /etc/profile
Method 2: Modify User Profile (Current User Only)
Add the same configuration to ~/.bashrc:
vi ~/.bashrc # open the file
# add the same configuration as above
source ~/.bashrc # apply the changes
4. Verifying the Environment Variable Configuration
After configuration, regardless of the OS, follow these steps to verify success:
- Close the current terminal and open a new one (to ensure the configuration is loaded).
- Run the following three commands. If all output the expected information, the configuration is successful:
Verify Java version: java -version
Example output (varies depending on JDK version):
java version "17.0.9" 2023-10-17 LTS
Java(TM) SE Runtime Environment (build 17.0.9+9-LTS-201)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.9+9-LTS-201, mixed mode, sharing)
Verify Java compiler (javac): javac -version
Example output: javac 17.0.9
Verify JAVA_HOME: echo $JAVA_HOME (Windows: echo %JAVA_HOME%)
Example output: D:\jdk17 (Windows) or /Library/Java/JavaVirtualMachines/jdk17.jdk/Contents/Home (macOS)
5. Common Troubleshooting
5.1 "java is not recognized as an internal or external command"
- Cause: The Path variable is missing %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (macOS/Linux), or the path is incorrect.
- Solution: Double-check the Path variable configuration. Ensure the path is correct and you've restarted the terminal after saving.
5.2 "javac" is not recognized
- Cause: JDK installation is incomplete (javac.exe is missing), or the Path variable doesn't include the JDK/bin directory.
- Solution: Reinstall the full JDK version. Verify that the Path variable includes the correct JDK/bin directory.
5.3 echo $JAVA_HOME shows nothing
- Cause: Incorrect profile edits (wrong file name or misspelled variable name), or the source command wasn't run to apply changes.
- Solution: Check the profile file (e.g., .zshrc, /etc/profile) to ensure the variable name is JAVA_HOME (all caps). Re-run the source command to apply changes.
5.4 %JAVA_HOME% not recognized on Windows
- Cause: JAVA_HOME is configured as a User Variable, but Path is configured as a System Variable (System Variables cannot reference User Variables).
- Solution: Move JAVA_HOME to System Variables, or use the absolute path directly in Path (e.g., "D:\jdk17\bin").
6. Important Notes
- Environment variable names are case-sensitive (JAVA_HOME cannot be written as java_home or Java_Home), especially on macOS and Linux.
- Paths must not contain Chinese characters, spaces, or special characters (e.g., avoid "D:\Java JDK" or "/Users/username/Desktop/JDK"), as this can cause command recognition failures.
- JDK 11 and above already include JRE, so you don't need to install JRE separately — just add %JAVA_HOME%\bin to Path.
- To switch JDK versions, simply change the JAVA_HOME variable to point to the new JDK root directory and restart the terminal.
Configuring Java environment variables is all about correctly setting JAVA_HOME and Path. The steps vary slightly across operating systems, but the logic is the same. Follow the steps in this article to get set up quickly and avoid development delays caused by environment issues. If you run into other configuration problems, search for solutions using the combination of "error message + OS + JDK version" as keywords, or refer to the official JDK documentation.
