[Gradle] Gradle 캐시와 사용자 홈(GRADLE_USER_HOME)

Gradle을 사용하다 보면, 거의 모든 복잡한 지시서 다국적인 사용성을 위해 캐시 구조를 재정리합니다.

하지만 또한 유연하게 발생할 수 있는 문제가, “같은 버전의 라이브러리를 다시 배포했을 때 변경사항이 반영되지 않는다”는 것입니다.

---

Gradle 캐시를 지워야 하는 이유

• 라이브러리를 같은 버전으로 다시 배포하거나 수정했을 경우, Gradle은 기존에 남아있는 캐시를 계속 사용
• Maven 저장소에서 삭제한 라이브러리를 IntelliJ 또는 Gradle에서 계속 찾을 수 있음
• 잘못된 라이브러리 .jar 파일 때문에 예기치 못한 오류 발생

---

Gradle 캐시가 저장되는 위치

~/.gradle/caches/modules-2/files-2.1/

구조 설명:

~/.gradle/
  └ caches/
      └ modules-2/
          └ files-2.1/
              └ groupId/
                  └ artifactId/
                      └ version/
                          └ hash/
                              └ artifact-version.jar

예시:

~/.gradle/caches/modules-2/files-2.1/org.apache.commons/commons-lang3/3.12.0/...

• modules-2: Gradle의 모듈 기반 캐시 디렉터리
• files-2.1: 파일 기반 아티팩트 저장 구조

---

Gradle user home(~/.gradle) 가 첫 시점에 어떻게 지정되는가?

Gradle은 다음 순서에 따라 user home 가 결정됩니다:

순서 방식 예시

1	환경 변수 GRADLE_USER_HOME	/Users/you/custom-gradle-dir
2	시스템 프로퍼티 -Dgradle.user.home	-Dgradle.user.home=/custom/path
3	기본값	~/.gradle

 

---

IntelliJ GUI에서 Gradle user home 지정하는 방법

1. File → Settings (macOS: IntelliJ IDEA → Preferences)
2. Build, Execution, Deployment → Build Tools → Gradle
3. Gradle user home 항목 확인
   • 비어 있으면 기본값(~/.gradle) 사용 중
   • 다른 경로 설정시, 해당 경로가 사용됨

⚠️ 이 설정은 해당 프로젝트에서만 적용

---

CLI에서 Gradle user home 지정하는 방법

환경변수로 지정 (지속적)

export GRADLE_USER_HOME=$HOME/custom-gradle-cache

• .bashrc, .zshrc 등에 추가하면 항상 적용

시스템 프로퍼티로 지정 (1회성)

./gradlew build -Dgradle.user.home=/tmp/gradle-tmp

• 이 명령어가 실행되는 동안만 해당 디렉터리를 캐시 경로로 사용

---

Gradle 캐시 삭제 방법

1. 캐시 수동 삭제

rm -rf ~/.gradle/caches/modules-2/files-2.1

가상의 특정 라이브러리만 삭제:

rm -rf ~/.gradle/caches/modules-2/files-2.1/com/dkt/aisp/da-kit/0.0.4

2. 캐시 강제 새로고침

./gradlew --refresh-dependencies

• 의존성 캐시를 무시하고, 원격 저장소에서 다시 받음
• 같은 버전의 라이브러리를 수정했을 경우 필요

---

ETC

캐시 경로 확인 Task 추가

tasks.register("printGradleUserHome") {
    doLast {
        println("Gradle user home: ${gradle.gradleUserHomeDir}")
    }
}

 

동작:

./gradlew printGradleUserHome

IntelliJ에서 특정 라이브러리 실제 경로 확인

1. External Libraries → 라이브러리 우클릭 → Show in Finder (mac) or Show in Explorer (Windows)
2. .jar 의 실제 캐시 경로 확인 가능

---

요약

캐시를 지워야 하는 이유	변경사항 무시, Maven 삭제했거나 파일 또는 IDE에서 계속 찾는 문제
캐시 기본 경로	~/.gradle/caches/modules-2/files-2.1
user home 결정 방식	환경값 → CLI 프로퍼티 → 기본값
GUI에서 설정	IntelliJ → Settings → Gradle
CLI에서 설정	환경값 또는 -Dgradle.user.home
캐시 삭제	수동 rm 또는 --refresh-dependencies