Gradle 명령어 모음: build, clean, test, bootRun 사용법
Gradlew 자주 쓰는 명령어 총정리: Spring Boot 빌드·실행·테스트·오류 해결까지
Gradle을 사용하는 Java 백엔드 개발자라면 ./gradlew build 정도는 익숙할 것입니다. 그런데 테스트 하나만 실행하고 싶을 때, 의존성이 제대로 내려받아지지 않을 때, Jenkins 빌드가 실패했을 때는 어떤 명령어를 사용해야 할까요?
Gradle 명령어를 전부 외울 필요는 없습니다. 자주 사용하는 명령어와 상황별 해결 명령어만 알아도 개발 중 발생하는 문제를 훨씬 빠르게 해결할 수 있습니다.
이 글에서는 Spring Boot 기반 Java 프로젝트를 기준으로 gradlew의 기본 개념부터 실무에서 자주 쓰는 명령어, 빌드 오류 대응, 멀티 모듈 프로젝트와 CI/CD 환경에서 활용하는 방법까지 정리합니다.
1. gradlew란 무엇일까?
gradlew는 Gradle Wrapper를 실행하기 위한 스크립트입니다. 프로젝트에서 지정한 Gradle 버전을 사용하므로 개발자마다 설치된 Gradle 버전이 달라 발생하는 문제를 줄일 수 있습니다. docs.gradle.orgdocs.gradle.org
일반적으로 프로젝트 루트에는 다음과 같은 파일이 있습니다.
my-project/
├── gradlew
├── gradlew.bat
├── settings.gradle
├── build.gradle
├── gradle/
│ └── wrapper/
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
└── src/
| 파일 | 역할 |
|---|---|
gradlew | macOS·Linux에서 실행하는 Wrapper 스크립트 |
gradlew.bat | Windows에서 실행하는 Wrapper 스크립트 |
gradle-wrapper.jar | Wrapper 실행에 필요한 JAR 파일 |
gradle-wrapper.properties | 사용할 Gradle 배포 버전과 다운로드 주소 등을 설정 |
운영체제별 실행 방법
macOS / Linux
./gradlew buildWindows PowerShell
.\gradlew.bat buildWindows에서는 gradlew.bat build 형태로 실행해도 됩니다.
실무 팁: 별도 이유가 없다면 시스템에 설치된 gradle보다 프로젝트에 포함된 Wrapper를 사용하는 것이 좋습니다. 로컬 개발 환경뿐 아니라 CI 서버에서도 프로젝트의 Gradle 버전을 일관되게 사용할 수 있기 때문입니다. docs.gradle.orgdocs.gradle.org
2. 가장 자주 쓰는 gradlew 명령어 10가지
먼저 아래 표부터 익혀 두세요. 일상적인 개발 업무에서 반복적으로 사용하기 좋은 명령어들입니다.
| 명령어 | 용도 |
|---|---|
./gradlew tasks | 실행 가능한 주요 작업 목록 확인 |
./gradlew clean | 빌드 결과물 삭제 |
./gradlew build | 프로젝트 빌드 및 연결된 검증 작업 수행 |
./gradlew clean build | 기존 빌드 결과물을 삭제한 뒤 빌드 |
./gradlew test | 테스트 작업 실행 |
./gradlew bootRun | Spring Boot 애플리케이션 실행 |
./gradlew bootJar | 실행 가능한 Spring Boot JAR 생성 |
./gradlew dependencies | 의존성 트리 확인 |
./gradlew --version | Wrapper가 사용하는 Gradle 및 JVM 정보 확인 |
./gradlew help | Gradle 도움말 확인 |
bootRun과 bootJar는 Spring Boot 플러그인이 적용된 프로젝트에서 일반적으로 사용할 수 있습니다. 모든 프로젝트에 같은 작업이 존재하는 것은 아니므로 tasks로 확인하는 습관을 들이세요. 기본 CLI 작업의 설명은 Gradle 공식 문서에서 확인할 수 있습니다. docs.gradle.orgdocs.gradle.org
3. 빌드 관련 명령어
3-1. ./gradlew build — 프로젝트 전체 빌드
./gradlew build코드를 컴파일하고, 설정된 테스트 및 검증 작업을 수행하며, 프로젝트에서 구성한 산출물을 생성하는 데 사용하는 대표 명령어입니다.
빌드가 성공하면 보통 다음과 같은 결과를 확인할 수 있습니다.
BUILD SUCCESSFUL반대로 BUILD FAILED가 표시된다면 컴파일 오류, 테스트 실패, 의존성 해결 문제 등을 확인해야 합니다.
3-2. ./gradlew clean — 빌드 결과물 삭제
./gradlew clean일반적으로 프로젝트의 build/ 디렉터리에 생성된 빌드 결과물을 삭제합니다.
소스 코드나 Git에 저장된 프로젝트 파일을 통째로 지우는 명령어는 아닙니다. 다만 삭제되는 빌드 산출물은 다음 빌드에서 다시 생성해야 하므로 빌드 시간이 늘어날 수 있습니다. docs.gradle.org
3-3. ./gradlew clean build — 깨끗한 상태에서 다시 빌드
./gradlew clean build다음과 같은 상황에서 활용할 수 있습니다.
- 이전 빌드 결과물이 문제를 일으키는 것으로 의심될 때
- 빌드 산출물을 새로 생성하고 싶을 때
- 로컬에서 정상적인 전체 빌드가 되는지 확인할 때
다만 모든 빌드 오류가 clean으로 해결되는 것은 아닙니다. 코드 오류나 잘못된 의존성 설정이라면 원인을 직접 수정해야 합니다.
3-4. ./gradlew assemble과 ./gradlew check의 차이
./gradlew assemble
./gradlew checkassemble: 프로젝트의 산출물을 조립하는 작업입니다.check: 테스트를 비롯해 프로젝트에 구성된 검증 작업을 수행하는 데 사용합니다.build: 일반적으로 산출물 생성과 검증을 함께 수행하는 상위 작업입니다.
세 작업의 정확한 실행 범위는 프로젝트의 플러그인과 작업 의존 관계에 따라 달라집니다. docs.gradle.org
4. Spring Boot 실행 및 JAR 생성 명령어
① 개발 환경에서 애플리케이션 실행
./gradlew bootRunSpring Boot 플러그인이 제공하는 bootRun 작업으로 애플리케이션을 실행합니다. 개발 중 서버를 빠르게 실행하고 로그를 확인할 때 유용합니다.
② 실행 가능한 JAR 생성
./gradlew bootJarSpring Boot 실행 가능한 JAR를 생성합니다. 기본 설정이라면 보통 build/libs/ 아래에서 확인할 수 있습니다.
③ 생성된 JAR 실행
java -jar build/libs/app.jarapp.jar는 예시 이름입니다. 실제 파일명과 경로는 프로젝트 설정에 맞춰야 합니다.
bootRun은 Gradle을 통해 애플리케이션을 실행하는 작업이고, bootJar는 배포 등에 활용할 수 있는 JAR 파일을 생성하는 작업입니다.
운영 환경에 배포할 때는 일반적으로 먼저 JAR를 생성하고, 실제 배포 대상 서버나 컨테이너에서 실행하는 방식으로 구분합니다.
프로파일을 지정해 실행하고 싶다면?
Spring Boot에서 local, dev, prod 같은 프로파일을 사용한다면 다음처럼 실행할 수 있습니다.
./gradlew bootRun --args='--spring.profiles.active=local'이 명령어는 Spring Boot 애플리케이션에 --spring.profiles.active=local 인자를 전달합니다. 프로젝트의 설정 파일, 환경변수, 비밀정보 관리 정책도 함께 확인해야 합니다.
5. 테스트 관련 명령어
테스트 작업은 단순히 전체 테스트를 실행하는 것 외에도 특정 클래스나 메서드만 실행할 수 있습니다.
전체 테스트 실행
./gradlew test프로젝트에 설정된 테스트 작업을 실행합니다.
특정 테스트 클래스만 실행
./gradlew test --tests "com.example.UserServiceTest"패키지명과 클래스명을 실제 프로젝트에 맞게 변경하세요.
특정 테스트 메서드만 실행
./gradlew test --tests "com.example.UserServiceTest.shouldCreateUser"테스트 클래스 전체가 아니라 한 메서드만 재실행할 때 편리합니다.
테스트를 강제로 다시 실행
./gradlew test --rerun-tasksGradle의 작업 결과 최신성 판단과 관계없이 해당 작업과 필요한 작업을 다시 실행하도록 요청합니다. docs.gradle.org
주의: --tests 옵션은 Java 테스트 작업에서 지원하는 옵션입니다. 테스트 프레임워크와 프로젝트 설정에 따라 실행 대상이 달라질 수 있습니다.
6. 의존성 관련 명령어
Java 백엔드 프로젝트에서는 라이브러리 버전 충돌, 저장소 접속 실패, 특정 라이브러리 미반영 문제가 발생할 수 있습니다. 이때는 의존성 관련 명령어를 활용하면 원인 분석에 도움이 됩니다.
6-1. 전체 의존성 확인
./gradlew dependencies프로젝트의 구성별 의존성을 트리 형태로 확인합니다. 직접 선언한 라이브러리뿐 아니라 다른 라이브러리를 통해 함께 포함되는 전이 의존성도 살펴볼 수 있습니다. docs.gradle.org
6-2. 특정 라이브러리의 의존성 경로 확인
./gradlew dependencyInsight --dependency jackson-databind특정 라이브러리가 왜 선택되었는지, 어떤 의존성 경로를 통해 포함되었는지 조사할 때 사용합니다.
멀티 모듈 프로젝트라면 대상 프로젝트를 지정해야 할 수 있습니다.
./gradlew :api:dependencyInsight --dependency jackson-databind여기서 api는 예시 모듈명입니다.
6-3. 의존성 정보 새로고침
./gradlew build --refresh-dependencies의존성 캐시를 새로 확인하도록 요청하는 옵션입니다. 저장소의 의존성 정보가 변경되었거나 캐시 상태가 실제 저장소와 맞지 않는 것으로 의심될 때 유용합니다.
단, 이 옵션이 모든 라이브러리를 무조건 다시 다운로드한다는 뜻은 아닙니다. Gradle은 필요에 따라 기존 파일을 재사용합니다. docs.gradle.org
6-4. 오프라인 모드로 빌드
./gradlew build --offline네트워크에 접속하지 않고 로컬 캐시에 있는 의존성만 사용해 빌드를 시도합니다.
인터넷 연결이 제한된 환경에서는 유용하지만, 필요한 라이브러리가 캐시에 없다면 빌드가 실패할 수 있습니다. docs.gradle.org
7. 빌드 오류가 발생했을 때 사용하는 옵션
명령어 자체보다 중요한 것은 실패 원인을 빠르게 좁히는 것입니다.
| 명령어 | 활용 상황 |
|---|---|
./gradlew build --stacktrace | 예외 발생 지점과 스택 트레이스 확인 |
./gradlew build --info | 작업 실행 및 빌드 과정의 추가 로그 확인 |
./gradlew build --debug | 더 상세한 진단 로그 확인 |
./gradlew build --scan | 빌드 분석 보고서 생성 시도 |
./gradlew tasks --all | 숨겨진 작업을 포함해 작업 목록 확인 |
./gradlew help --task bootRun | 특정 작업의 사용법과 정보 확인 |
Gradle은 --stacktrace, --info, --debug 등으로 진단 정보를 늘릴 수 있습니다. --debug에는 환경에 따라 민감한 정보가 포함될 가능성이 있으므로 로그를 공유하기 전에는 반드시 검토하세요. docs.gradle.orgdocs.gradle.org
오류 유형별 추천 명령어
(상황 1)
컴파일 오류 또는 테스트 실패
./gradlew build --stacktrace가장 먼저 실패한 작업과 최초 오류 메시지를 확인합니다. 로그 마지막 부분만 보는 것보다 최초 원인을 찾는 것이 중요합니다.
(상황 2)
라이브러리 버전이나 캐시 문제 의심
./gradlew build --refresh-dependencies의존성을 새로 확인하도록 합니다. 단순한 Java 컴파일 오류라면 이 명령어만으로 해결되지 않습니다.
(상황 3)
어떤 작업이 실행되는지 먼저 확인
./gradlew build --dry-run실제 작업 동작을 수행하지 않고 어떤 작업들이 실행 대상인지 살펴봅니다. 실행 계획을 확인하는 용도로 사용하세요.
(상황 4)
여러 검증 작업의 실패를 함께 확인
./gradlew test --continue실패한 작업이 있더라도 실행 가능한 다른 작업을 계속 진행하도록 요청합니다. 다만 의존 작업이 실패해 실행할 수 없는 작업은 진행되지 않습니다.
--dry-run과 --continue의 동작은 Gradle 공식 CLI 문서에 설명되어 있습니다. docs.gradle.orgdocs.gradle.org
8. 멀티 모듈 프로젝트에서 사용하는 명령어
실무에서는 하나의 저장소에 api, batch, common 같은 여러 모듈이 존재하는 프로젝트도 많습니다.
이때는 모듈 이름을 지정해 필요한 작업만 실행할 수 있습니다.
# 프로젝트 구조 확인
./gradlew projects
# 주요 작업 목록 확인
./gradlew tasks
# api 모듈 빌드
./gradlew :api:build
# api 모듈 테스트
./gradlew :api:test
# batch 모듈 빌드
./gradlew :batch:buildprojects는 하위 프로젝트 구조를, tasks는 주요 작업 목록을 확인하는 데 사용합니다. 콜론으로 시작하는 프로젝트 경로는 루트 프로젝트를 기준으로 작업을 지정하는 방식입니다. docs.gradle.orgdocs.gradle.org
모듈명은 예시이므로 ./gradlew projects 결과에 나온 실제 이름을 사용해야 합니다.
하위 모듈에서 실행할 때 주의할 점
루트 디렉터리가 아닌 하위 모듈 디렉터리에서 명령어를 실행한다면 Wrapper 경로를 확인하세요.
# 루트에서 실행
./gradlew :api:test
# api 디렉터리에서 루트 Wrapper를 호출하는 예시
../gradlew test실제 상대 경로는 디렉터리 구조에 따라 달라집니다.
9. Gradle 버전 및 JVM 확인
Gradle 명령어가 정상적으로 실행되지 않거나 로컬과 Jenkins의 빌드 결과가 다르다면 Gradle 버전과 Java 실행 환경부터 확인해 보세요.
./gradlew --version이 명령어는 Gradle 버전뿐 아니라 실행에 관련된 JVM과 운영체제 정보도 보여 줍니다. docs.gradle.orgdocs.gradle.org
Wrapper에서 사용할 Gradle 버전을 변경하려면 다음과 같이 실행할 수 있습니다.
./gradlew wrapper --gradle-version 8.148.14는 명령어 사용 예시일 뿐, 현재 프로젝트에 적용해야 하는 버전을 의미하지는 않습니다. 프로젝트의 Spring Boot 버전, JDK 버전, 플러그인 호환성을 확인한 뒤 변경해야 합니다.
Wrapper 버전을 관리할 때는 생성된 Wrapper 관련 파일을 소스 관리에 포함해 개발 환경과 CI 환경에서 동일한 설정을 사용하도록 합니다. docs.gradle.orgdocs.gradle.org
자주 묻는 질문(FAQ)
Q1. gradle build와 ./gradlew build는 무엇이 다른가요?
gradle build는 시스템에 설치된 Gradle을 사용합니다. 반면 ./gradlew build는 프로젝트의 Wrapper 설정에 지정된 Gradle 버전을 사용합니다. 팀 프로젝트에서는 버전 차이로 인한 문제를 줄이기 위해 Wrapper 사용을 권장합니다. docs.gradle.orgdocs.gradle.org
Q2. clean build를 매번 실행해야 하나요?
아닙니다. 일반적인 개발 과정에서는 build만으로 충분한 경우가 많습니다. 이전 산출물과 관련된 문제가 의심되거나 깨끗한 상태에서 전체 빌드를 확인해야 할 때 clean build를 사용하면 됩니다.
Q3. --refresh-dependencies를 사용하면 모든 라이브러리를 다시 다운로드하나요?
그렇지 않습니다. Gradle이 저장소의 의존성 정보를 다시 확인하지만, 변경되지 않은 파일은 검증 후 재사용할 수 있습니다. docs.gradle.org
Q4. bootRun은 성공했는데 bootJar는 실패할 수 있나요?
가능합니다. 두 작업은 실행 목적이 다릅니다. 실행 환경에서 필요한 설정이나 의존성은 정상이어도 패키징 과정에서 별도의 오류가 발생할 수 있습니다. 실제 배포에 사용하는 방식에 맞춰 JAR 생성과 실행까지 확인하는 것이 좋습니다.
Q5. Jenkins에서는 성공하는데 로컬에서는 실패합니다. 무엇부터 확인해야 하나요?
먼저 다음 항목을 비교하세요.
./gradlew --version으로 확인한 Gradle 및 JVM 정보- 프로젝트가 요구하는 JDK 버전과 실제 사용 중인 JDK
- 환경변수와 외부 설정 파일
- 저장소 접근 권한 및 의존성 다운로드 가능 여부
- 운영체제별 경로, 파일 권한, 대소문자 차이
단순히 clean을 반복하기보다는 최초 오류 메시지와 실행 환경 차이를 확인하는 편이 문제 해결에 도움이 됩니다.
마무리: 이것만은 기억하세요!
Gradle 명령어를 처음부터 전부 외울 필요는 없습니다. 우선 아래 6개부터 익혀 보세요.
./gradlew build— 전체 빌드./gradlew clean build— 깨끗한 상태에서 재빌드./gradlew test— 테스트 실행./gradlew bootRun— Spring Boot 실행./gradlew build --stacktrace— 오류 원인 추적./gradlew dependencies— 의존성 구조 확인
여기에 멀티 모듈 작업 경로, --info, --refresh-dependencies를 더 익히면 로컬 개발부터 Jenkins 빌드 오류 분석까지 대응할 수 있는 범위가 넓어집니다.
핵심은 명령어 암기가 아니라, 지금 발생한 문제에 어떤 명령어가 필요한지 판단하는 능력입니다.
참고 자료
- Gradle 공식 문서 — Command-Line Interface
- Gradle 공식 문서 — Gradle Wrapper
- Gradle 공식 문서 — Dependency Caching
명령어와 옵션은 프로젝트의 Gradle 버전, 적용된 플러그인 및 빌드 설정에 따라 일부 차이가 있을 수 있습니다. 실제 적용 전에는 프로젝트에서 제공하는 작업 목록과 공식 문서를 함께 확인하세요.