Keywords: macOS | Environment Variables | Maven Configuration | Terminal Issues | .bash_profile
Abstract: This technical paper provides an in-depth analysis of the 'mvn command not found' error in macOS systems, focusing on environment variable persistence across terminal sessions. It presents a complete solution using .bash_profile for global Maven availability, covers proper JAVA_HOME and M2_HOME configuration, and discusses alternative approaches including symbolic links and Homebrew installation methods.
Problem Background and Root Cause Analysis
In macOS systems, users frequently encounter situations where the mvn command works properly in one terminal session but returns command not found in newly opened terminals. This phenomenon stems from the limited scope of environment variable configurations.
When users set environment variables directly using the export command in terminal, these variables are only effective for the current shell session and its child processes. Once the terminal window is closed, these temporary settings are lost. This explains why Maven commands work in the terminal where installation was performed but remain unrecognized in new terminal sessions.
Persistent Environment Variable Configuration
To make Maven commands available across all terminal sessions, environment variables must be configured in shell startup files. For bash shell, the most appropriate choice is the .bash_profile file.
First, verify the correct path configurations:
# Check current configuration in working terminal
env | grep M2_HOME
env | grep JAVA_HOME
After obtaining the correct paths, edit or create the ~/.bash_profile file:
vi ~/.bash_profile
Add the following configuration content to the file:
# Java environment configuration
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_40.jdk/Contents/Home
export JAVA_HOME
# Maven environment configuration
M2_HOME=/usr/local/apache-maven/apache-maven-3.1.1
export M2_HOME
# Path configuration
PATH=$PATH:$JAVA_HOME/bin:$M2_HOME/bin
export PATH
After saving the file, execute the following command to make the configuration take effect immediately:
source ~/.bash_profile
Now, when opening a new terminal window, the command mvn --version should properly display Maven version information.
Alternative Solutions
Beyond environment variable configuration, several other viable solutions exist.
The symbolic link approach leverages existing system PATH by linking Maven executables to the /usr/local/bin directory:
# Extract Maven installation package
cd ~/Downloads
tar xvf apache-maven-3.5.3-bin.tar.gz
# Move installation directory
mv apache-maven-3.5.3 /usr/local/
# Create symbolic link
cd /usr/local/bin
sudo ln -s ../apache-maven-3.5.3/bin/mvn mvn
Using Homebrew package manager provides another streamlined installation method:
brew install maven
After installation, verify the result using mvn -v.
Configuration Verification and Troubleshooting
After completing configuration, comprehensive verification is essential:
# Check Maven version
mvn --version
# Check Java environment
echo $JAVA_HOME
# Check Maven home directory
echo $M2_HOME
# Verify command location
which mvn
If issues persist, check for these common errors:
- Path spelling mistakes
- File permission issues
- Shell configuration file loading order
- Terminal type mismatches
Through systematic environment variable configuration, Maven development tools can achieve stable availability in macOS systems, providing reliable foundational environment support for Java project development.