이번 포스팅에서는 Java 버전 관리 도구인 jenv에 대해서 정리하고자 한다. 프로젝트마다 요구하는 Java 버전이 다르면 매번 JAVA_HOME을 수동으로 바꿔야 하는 번거로움이 생긴다. Spring Boot 3.x는 Java 17 이상을 요구하고, 레거시 시스템은 여전히 Java 8이나 11을 쓰는 현실에서 하나의 장비에 여러 JDK를 설치하고 전환하는 작업은 피할 수 없다. jenv는 이 문제를 디렉토리 단위로 해결해 주는 경량 도구다. GitHub 스타 약 6,500개를 보유한 이 프로젝트는 rbenv에서 영감을 받아 만들어졌으며, Shell 스크립트 기반이라 설치와 설정이 간단하다.
jenv가 뭔데, 왜 필요한가
jenv는 공식 사이트에서 스스로를 “JAVA_HOME 설정 방법을 잊게 해주는 도구”라고 소개한다.
global 설정으로 시스템 전체의 기본 Java 버전을 지정하고, local 설정으로 특정 프로젝트 디렉토리에 진입하면 자동으로 해당 버전이 활성화된다. shell 설정은 현재 터미널 세션에서만 임시로 다른 버전을 쓸 때 사용한다.
이 세 단계의 우선순위는 shell > local > global 순서다. 프로젝트 디렉토리에 .java-version 파일이 있으면 해당 버전이 자동 적용되고, 터미널에서 jenv shell로 지정한 값이 있으면 그것이 최우선이다.
한 가지 명확히 해둘 점이 있다. jenv는 JDK를 설치해 주지 않는다. Homebrew나 각 벤더의 설치 파일로 JDK를 먼저 설치한 뒤, jenv에 해당 경로를 등록하는 방식이다.
macOS에서 jenv 설치하기
macOS에서는 Homebrew를 사용하는 방법이 가장 간단하다.
# Homebrew로 jenv 설치
brew install jenv설치 후 사용 중인 Shell에 따라 초기화 스크립트를 추가해야 한다. Zsh 사용자(macOS 기본 Shell)라면 ~/.zshrc에 아래 두 줄을 추가한다.
# ~/.zshrc에 추가
export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"위 설정에서 첫 번째 줄은 jenv 실행 파일의 경로를 PATH에 추가하는 것이고, 두 번째 줄은 Shell이 시작될 때 jenv의 shim과 자동 완성 기능을 초기화하는 역할을 한다. eval "$(jenv init -)" 없이는 jenv의 버전 전환 기능이 작동하지 않으므로 반드시 추가해야 한다.
Bash 사용자라면 동일한 내용을 ~/.bash_profile에 추가하면 된다.
# Bash 사용자: ~/.bash_profile에 추가
export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"설정을 저장한 뒤 Shell을 재시작한다.
# Shell 재시작
exec $SHELL -l이 명령은 현재 Shell 프로세스를 새로 시작하여 방금 추가한 설정을 즉시 반영한다. 터미널을 닫았다 열어도 동일한 효과가 있다.
Linux에서 jenv 설치하기
Linux에서는 Git을 이용해 직접 클론하는 방식으로 설치한다.
# Git으로 jenv 소스 클론
git clone https://github.com/jenv/jenv.git ~/.jenv이후 Shell 설정 파일에 PATH와 초기화 스크립트를 추가하는 과정은 macOS와 동일하다.
# ~/.bashrc 또는 ~/.zshrc에 추가
export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"위 설정을 추가한 뒤 exec $SHELL -l로 Shell을 재시작하면 jenv 명령을 사용할 수 있다. Linux에서 주의할 점은 배포판에 따라 JDK 설치 경로가 /usr/lib/jvm/ 아래에 위치하는 경우가 많다는 것이다.
JDK 설치와 jenv 등록
jenv는 JDK 설치 기능을 제공하지 않으므로, 먼저 원하는 버전의 JDK를 설치한 뒤 경로를 등록해야 한다. macOS에서 Homebrew를 쓴다면 아래처럼 설치한다.
# OpenJDK 17 설치
brew install openjdk@17
# OpenJDK 21 설치
brew install openjdk@21
# Temurin(Eclipse Adoptium) JDK 설치
brew install --cask temurin@17
brew install --cask temurin@21Homebrew로 설치한 OpenJDK는 /usr/local/opt/openjdk@{버전}/libexec/openjdk.jdk/Contents/Home 경로에 위치한다(Apple Silicon Mac에서는 /opt/homebrew/opt/ 아래). Temurin은 /Library/Java/JavaVirtualMachines/temurin-{버전}.jdk/Contents/Home에 설치된다.
설치된 JDK를 jenv에 등록하는 명령은 jenv add다.
# Homebrew OpenJDK 17 등록 (Apple Silicon Mac 기준)
jenv add /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
# Homebrew OpenJDK 21 등록
jenv add /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
# Temurin JDK 등록
jenv add /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Homejenv add 명령을 실행하면 jenv가 해당 JDK의 버전 정보를 자동으로 인식하여 여러 별칭(major, minor, patch)을 생성한다. 예를 들어 OpenJDK 21.0.2를 등록하면 21, 21.0, 21.0.2 세 가지 이름으로 접근할 수 있다.
등록된 전체 버전 목록을 확인하려면 jenv versions를 실행한다.
# 등록된 Java 버전 목록 확인
jenv versions실행하면 이런 식으로 출력된다.
system
17
17.0
17.0.13
21
21.0
21.0.2
* 21.0.2 (set by /Users/dev/.jenv/version)* 표시가 현재 활성화된 버전을 나타낸다. system은 OS에 기본 설치된 Java를 가리킨다.
프로젝트별 Java 버전 전환의 세 가지 방법
jenv의 핵심 기능은 global, local, shell 세 단계로 Java 버전을 전환하는 것이다.
global: 시스템 전체 기본 버전
# 시스템 기본 Java를 21로 설정
jenv global 21
# 현재 글로벌 버전 확인
jenv global이 설정은 ~/.jenv/version 파일에 저장되며, 다른 설정이 없는 모든 디렉토리에서 이 버전이 적용된다. 주로 가장 자주 사용하는 최신 LTS 버전을 global로 지정해 두는 것이 편리하다.
local: 디렉토리별 버전 고정
# 현재 프로젝트 디렉토리에서 Java 17 사용
cd ~/projects/legacy-api
jenv local 17이 명령은 해당 디렉토리에 .java-version이라는 파일을 생성하고, 그 안에 17이라는 값을 기록한다. 이후 이 디렉토리에 진입할 때마다 jenv가 자동으로 Java 17을 활성화한다.
# .java-version 파일 내용 확인
cat .java-version
# 출력: 17.java-version 파일은 프로젝트 루트에 위치하므로 Git으로 버전 관리할 수 있다. 팀원 모두가 jenv를 사용한다면 이 파일을 커밋해 두면 프로젝트를 클론한 뒤 별도 설정 없이 올바른 Java 버전이 적용된다.
shell: 현재 터미널 세션 전용
# 현재 터미널에서만 임시로 Java 11 사용
jenv shell 11이 설정은 환경 변수 JENV_VERSION을 통해 작동하며, 터미널을 닫으면 사라진다. 특정 버전에서 빌드 테스트를 잠깐 해보고 싶을 때 유용하다.
# shell 버전 설정 해제
jenv shell --unset세 가지 설정의 우선순위를 정리하면 아래 표와 같다.
| 우선순위 | 설정 방법 | 저장 위치 | 지속 범위 |
|---|---|---|---|
| 1 (최우선) | jenv shell | 환경변수 JENV_VERSION | 현재 터미널 세션 |
| 2 | jenv local | .java-version 파일 | 해당 디렉토리 |
| 3 | jenv global | ~/.jenv/version | 시스템 전체 |
JAVA_HOME 자동 설정: export 플러그인
jenv를 설치한 직후 가장 먼저 해야 할 설정이 export 플러그인 활성화다. 이 플러그인이 없으면 jenv가 java 명령의 경로만 바꿀 뿐, JAVA_HOME 환경변수는 갱신하지 않는다.
# export 플러그인 활성화 (필수)
jenv enable-plugin export
# Shell 재시작
exec $SHELL -lexport 플러그인은 jenv가 버전을 전환할 때마다 JAVA_HOME과 JDK_HOME 환경변수를 자동으로 갱신해 준다. Maven, Gradle, IntelliJ IDEA 등 대부분의 Java 빌드 도구와 IDE는 JAVA_HOME을 참조하므로, 이 플러그인 없이는 jenv의 버전 전환이 빌드 도구에 반영되지 않는 문제가 발생한다.
제대로 설정되었는지 확인하는 방법은 간단하다.
# JAVA_HOME이 jenv 설정을 따르는지 확인
echo $JAVA_HOME
# 출력 예: /Users/dev/.jenv/versions/21
jenv javahome
# 출력 예: /Users/dev/.jenv/versions/21위 두 명령의 출력이 일치하면 export 플러그인이 정상 작동하는 것이다. 일치하지 않는다면 ~/.zshrc(또는 ~/.bash_profile)에서 다른 곳에서 JAVA_HOME을 하드코딩하고 있지 않은지 확인해야 한다.
Maven과 Gradle 플러그인 연동
jenv는 Maven과 Gradle용 플러그인도 제공한다. 이 플러그인을 활성화하면 mvn이나 gradle 명령 실행 시 jenv가 관리하는 Java 버전이 자동으로 적용된다.
# Maven 플러그인 활성화
jenv enable-plugin maven
# Gradle 플러그인 활성화
jenv enable-plugin gradle
# 전체 플러그인 목록 확인 (활성화된 플러그인은 * 표시)
jenv pluginsMaven 플러그인은 mvn 명령에 대한 shim(래퍼 스크립트)을 생성하는 동시에, 실행 시 MAVEN_OPTS를 통해 jenv가 관리하는 JDK 옵션을 전달한다. Gradle 플러그인도 동일한 방식으로 gradle 명령의 shim을 생성하고 GRADLE_OPTS를 설정한다. export 플러그인만으로도 JAVA_HOME이 올바르게 설정되지만, Maven/Gradle 플러그인은 추가적인 안전장치 역할을 한다.
# 플러그인 활성화 후 올바른 JDK가 적용되는지 확인
jenv local 17
mvn -version # Java home 항목이 jenv의 17 버전 경로를 가리키는지 확인위 명령에서 mvn -version 출력의 Java home 항목이 jenv가 관리하는 JDK 17 경로를 표시하면 정상이다. export 플러그인과 Maven 플러그인을 함께 활성화해 두면 이중으로 올바른 JDK 적용을 보장받을 수 있다.
정리하면, jenv 설치 직후 반드시 활성화해야 할 플러그인은 export, maven, gradle 세 가지다. 이 세 플러그인이 활성화되어야 jenv가 터미널 환경과 빌드 도구 양쪽 모두에서 일관되게 동작한다.
jenv doctor로 설정 상태 진단하기
jenv에는 현재 설정 상태를 점검하는 jenv doctor 명령이 내장되어 있다.
# jenv 설정 상태 진단
jenv doctor정상이라면 이렇게 나온다.
[OK] No JAVA_HOME set
[OK] Java binaries in path are jenv shims
[OK] Jenv is correctly loaded위처럼 세 항목 모두 [OK]가 나오면 jenv가 올바르게 설정된 상태다. [ERROR]가 표시되는 항목이 있다면 주로 다음 두 가지 원인이다.
첫째, ~/.zshrc에서 JAVA_HOME을 직접 export하고 있는 경우다. jenv의 export 플러그인과 충돌하므로 수동 설정을 제거해야 한다.
둘째, eval "$(jenv init -)"가 PATH 설정보다 뒤에 위치하지 않는 경우다. ~/.zshrc에서 jenv 관련 두 줄의 순서가 올바른지 확인한다.
실전 시나리오: 프로젝트 세 개를 동시에 관리하기
실무에서 흔한 상황을 하나 들어 보자. 아래처럼 세 프로젝트를 동시에 맡고 있다고 가정한다.
# 프로젝트별 Java 버전 설정
cd ~/projects/payment-gateway # Spring Boot 2.7 → Java 11 필요
jenv local 11
cd ~/projects/order-service # Spring Boot 3.3 → Java 17 필요
jenv local 17
cd ~/projects/ai-recommender # 최신 기능 활용 → Java 21 필요
jenv local 21위 명령으로 각 프로젝트 디렉토리에 .java-version 파일이 생성된다. 이제 터미널에서 디렉토리를 이동할 때마다 Java 버전이 자동으로 전환된다.
# 디렉토리 이동 시 자동 전환 확인
cd ~/projects/payment-gateway
java -version
# openjdk version "11.0.24"
cd ~/projects/order-service
java -version
# openjdk version "17.0.13"
cd ~/projects/ai-recommender
java -version
# openjdk version "21.0.2"별도의 스크립트나 수동 설정 없이 cd만으로 Java 버전이 전환되는 것을 확인할 수 있다. jenv가 Shell 진입 시 .java-version 파일을 읽어 자동으로 shim 경로를 전환하기 때문이다.
IntelliJ IDEA와 jenv 함께 쓰기
IntelliJ IDEA에서 프로젝트를 열 때 jenv로 등록한 JDK를 SDK로 추가하면 터미널과 IDE의 Java 버전을 일치시킬 수 있다.
# jenv에 등록된 JDK의 실제 경로 확인
jenv javahome
# 출력: /Users/dev/.jenv/versions/17
# 이 경로는 심볼릭 링크로, 실제 JDK 경로를 가리킨다
# 실제 JDK 경로 확인
ls -la /Users/dev/.jenv/versions/17
# lrwxr-xr-x 17 -> /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/HomeIntelliJ에서 File > Project Structure > SDKs에 위 실제 경로를 추가하면 된다. 또는 ~/.jenv/versions/{버전} 심볼릭 링크 경로를 직접 지정해도 동작한다.
macOS에서 IntelliJ와 같은 GUI 애플리케이션은 Shell 환경변수를 상속받지 않는다. 이 경우 jenv의 macos-javahome 명령을 사용할 수 있다.
# macOS GUI 앱용 JAVA_HOME 설정
jenv macos-javahome이 명령은 /Library/Java/JavaVirtualMachines/ 아래에 심볼릭 링크를 생성하여 macOS의 /usr/libexec/java_home 유틸리티가 jenv의 global 버전을 인식하도록 만든다. 단, 이 설정은 global 버전만 반영하며 local이나 shell 설정에 따라 동적으로 변경되지 않는다.
jenv와 SDKMAN, 어떤 상황에서 어떤 도구를 쓸까
Java 버전 관리 도구로 SDKMAN도 많이 쓰인다. 둘 다 써본 입장에서 정리하면 이렇다.
sdkman 사용법에 대해서는 SDKMAN 설치부터 실전 활용까지: 자바 버전 관리 완벽 가이드 (2026) 포스팅을 참고하기 바란다.
| 비교 항목 | jenv | SDKMAN |
|---|---|---|
| JDK 설치 | 지원 안 함 (별도 설치 필요) | sdk install java 21-tem으로 직접 설치 |
| 관리 대상 | JDK 경로 전환만 담당 | JDK + Maven + Gradle + Kotlin + Scala 등 |
| 버전 전환 | .java-version 파일 기반 자동 전환 | .sdkmanrc 파일 기반 ( sdkman_auto_env=true 설정 시 자동 전환) |
| 설치 크기 | Shell 스크립트 수백 KB | curl 기반 설치, 약 5MB |
| 적합한 상황 | Homebrew로 JDK를 관리하는 macOS 사용자 | JDK 설치부터 빌드 도구까지 함께 관리하고 싶은 경우 |
jenv는 “이미 설치된 JDK를 가볍게 전환하고 싶다”는 단일 목적에 충실한 도구다. Homebrew로 JDK를 설치하고 있고, Maven이나 Gradle은 별도로 관리하는 워크플로에 잘 맞는다.
반면 SDKMAN은 JDK 설치, Maven 설치, Gradle 설치를 한 도구로 통합하고 싶을 때 적합하다. 다만 두 도구를 동시에 사용하면 JAVA_HOME 설정이 충돌할 수 있으므로, 하나를 선택해서 사용하는 것을 권장한다.
자주 겪는 문제와 해결법
JAVA_HOME이 jenv 설정을 따르지 않는 경우
# 증상: jenv로 17 설정했는데 JAVA_HOME은 21을 가리킴
jenv local 17
echo $JAVA_HOME
# /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home ← 불일치해결 방법은 두 가지다.
# 1. export 플러그인 활성화 확인
jenv enable-plugin export
exec $SHELL -l
# 2. ~/.zshrc에서 JAVA_HOME 수동 설정 제거
# 아래와 같은 줄이 있다면 삭제한다
# export JAVA_HOME=$(/usr/libexec/java_home -v 21)jenv add 시 “not a valid path” 에러
JDK 경로를 정확히 지정해야 한다. macOS에서는 .jdk 디렉토리 안의 Contents/Home까지 포함해야 한다.
# 잘못된 경로
jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk
# → not a valid path to java installation
# 올바른 경로
jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
# → oracle64-21.0.2 added등록된 버전 제거하기
더 이상 사용하지 않는 JDK 버전은 jenv remove로 jenv 등록을 해제할 수 있다.
# 특정 버전의 jenv 등록 해제
jenv remove 11.0.24
# 전체 버전 목록에서 해제 확인
jenv versionsjenv remove는 jenv의 심볼릭 링크만 삭제하며, 실제 JDK 파일은 그대로 남아 있다. JDK 자체를 삭제하려면 Homebrew의 brew uninstall 또는 해당 디렉토리를 직접 삭제해야 한다.
jenv 설정 한 장 요약 체크시트
지금까지 다룬 내용을 명령어 순서대로 한 곳에 모았다. 복사해서 바로 쓰면 된다.
# 1. jenv 설치
brew install jenv
# 2. Shell 설정 (~/.zshrc)
export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"
# 3. Shell 재시작
exec $SHELL -l
# 4. 필수 플러그인 활성화
jenv enable-plugin export
jenv enable-plugin maven
jenv enable-plugin gradle
# 5. JDK 등록
jenv add /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
jenv add /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
# 6. 글로벌 기본 버전 설정
jenv global 21
# 7. 프로젝트별 버전 고정
cd ~/projects/legacy-api && jenv local 17
# 8. 설정 상태 확인
jenv doctor위 8단계를 순서대로 실행하면 jenv 설정이 완료된다. 이후에는 프로젝트 디렉토리를 이동할 때마다 Java 버전이 자동으로 전환되고, Maven과 Gradle 빌드에도 올바른 JDK가 적용된다.
마치며
지금까지 jenv의 설치부터 실전 활용까지 정리해 보았다. 개인적으로 jenv를 쓰기 시작한 건 Spring Boot 2.x에서 3.x로 마이그레이션하는 프로젝트를 병행하면서부터였다. 두 프로젝트를 오가며 매번 ~/.zshrc의 JAVA_HOME을 수정하고 source ~/.zshrc를 실행하던 시절을 생각하면, cd 한 번으로 버전이 바뀌는 지금이 훨씬 편하다. 도구 자체가 Shell 스크립트 몇 개로 이루어져 있어서 가볍고, 한번 세팅하면 건드릴 일이 거의 없다는 점도 마음에 든다.
함께 보면 좋은 글
- SDKMAN 설치부터 실전 활용까지: 자바 버전 관리 완벽 가이드 (2026) — jenv와 자주 비교되는 JVM 생태계 통합 관리 도구. JDK 설치까지 한 번에 해결하고 싶다면 이 글을 참고한다.
- mise 버전 관리: nvm, pyenv, sdkman을 하나로 통합하는 방법 — Java뿐 아니라 Node.js, Python 등 여러 런타임의 버전을 하나의 도구로 관리하는 mise 사용법을 다룬다.
- 모던 CLI 도구로 터미널 생산성 5배 올리기 — fzf부터 zoxide까지 실전 연동 — jenv와 함께 터미널 워크플로를 개선할 수 있는 CLI 도구 모음을 정리했다.
- tmux 사용법 정리: 설치부터 플러그인까지 터미널 멀티플렉서 입문 — 여러 프로젝트를 동시에 다룬다면 tmux로 터미널 세션을 분리하는 것도 생산성에 도움이 된다.
- JDK 21에서 JDK 25로: 성능 업데이트 — jenv로 전환할 JDK 버전별 성능 차이가 궁금하다면 이 벤치마크 비교를 참고한다.
FAQ
jenv는 JDK를 설치해주나?
아니다. jenv는 JDK 설치 기능이 없고, 이미 설치된 JDK 간의 버전 전환만 담당한다. JDK는 Homebrew(brew install –cask temurin@21), Adoptium 공식 사이트, 또는 SDKMAN을 통해 별도로 설치한 뒤 jenv add 명령으로 등록해야 한다.
jenv와 SDKMAN 중 어떤 것을 써야 하나?
JDK 버전 전환만 필요하다면 jenv가 가볍고 단순하다. JDK 설치까지 한 도구에서 해결하거나 Gradle, Maven 같은 빌드 도구 버전도 함께 관리하고 싶다면 SDKMAN이 적합하다. 두 도구를 동시에 설치해도 충돌하지 않으므로, jenv로 시작해서 필요하면 SDKMAN을 추가하는 방식도 가능하다.
jenv 설정 후 JAVA_HOME이 바뀌지 않는 이유는?
jenv는 기본적으로 JAVA_HOME 환경변수를 변경하지 않는다. jenv enable-plugin export 명령으로 export 플러그인을 활성화한 뒤 shell을 재시작해야 JAVA_HOME이 jenv가 선택한 버전으로 자동 설정된다. Gradle이나 IntelliJ 같은 도구가 JAVA_HOME을 참조하므로 이 플러그인 활성화는 사실상 필수이다.
jenv는 Windows에서 사용할 수 있나?
공식적으로 jenv는 macOS와 Linux만 지원한다. Windows에서는 WSL2를 통해 사용하거나, 네이티브 대안으로 jabba 또는 SDKMAN(WSL 환경)을 고려할 수 있다. Windows 네이티브 환경에서 Java 버전 관리가 필요하다면 IntelliJ의 Project SDK 설정이나 Gradle의 toolchain 기능을 활용하는 것이 현실적이다.
jenv local과 jenv shell의 차이는 무엇인가?
jenv local은 현재 디렉토리에 .java-version 파일을 생성하여 해당 프로젝트에 들어올 때마다 자동으로 Java 버전을 전환한다. jenv shell은 현재 터미널 세션에서만 일시적으로 버전을 변경하며, 터미널을 닫으면 원래 설정으로 돌아간다. 프로젝트별 고정 버전은 local, 일회성 테스트는 shell을 사용한다.
더 알아보기
- jenv 공식 GitHub – 소스 코드, 이슈 트래커, 위키
- jenv 공식 사이트 – 설치 가이드, 기본 사용법
- Baeldung – Managing Multiple JDK Installations With jEnv – 상세 튜토리얼
- Configuring jenv the right way – 실전 설정 팁