지니제스트 테크 블로그 배너
지니제스트Tech Archive
모바일9분 소요

adb install INSTALL_FAILED 오류 코드별 원인과 해결

•
지지니제스트
•조회 2

adb install이 Failure [INSTALL_FAILED_...]로 끝날 때 오류 코드별 원인과 조치를 정리했습니다. 서명 불일치, ABI 불일치, 저장 공간, 버전 다운그레이드, minSdk, Xiaomi USER_RESTRICTED까지 다룹니다.

adb install INSTALL_FAILED 오류 코드별 원인과 해결

adb install이 Failure [INSTALL_FAILED_...]로 끝나면 대괄호 안의 코드가 실패 원인을 알려줍니다. 앱 안에서 보이는 "앱이 설치되지 않았습니다" 같은 일반 메시지보다 훨씬 구체적이므로, 먼저 이 코드를 확인하면 대부분 한두 단계 안에 원인이 좁혀집니다.

이 글은 자주 만나는 오류 코드의 원인과 조치를 코드별로 정리했습니다. 오류 코드 숫자는 PackageManager 상수 값이며, 기기나 Android 버전에 따라 출력 형식이 조금 다를 수 있습니다.


증상과 로그로 원인 좁히기

앱 설치 실패 시 adb install 명령은 Failure [INSTALL_FAILED_...] 형식의 오류 메시지를 반환하여 구체적인 실패 원인을 알려줍니다. 이 오류 코드를 확인하는 것이 가장 중요하며, 때로는 adb logcat 명령을 통해 기기의 시스템 메시지 로그를 확인하면 더 자세한 원인을 파악할 수 있습니다. 특히 Play 스토어를 통한 설치 문제라면 adb logcat | grep Finsky로 Play 스토어 로그만 걸러 볼 수 있습니다.

다음 표는 자주 보는 오류 코드와 첫 조치를 요약한 것입니다.

오류 코드 의미 첫 조치
INSTALL_FAILED_ALREADY_EXISTS (-1) 같은 패키지가 이미 설치되어 있음 adb install -r <apk>로 데이터를 유지한 채 재설치
INSTALL_FAILED_INVALID_APK (-2) APK가 손상됐거나 Split APK 구성이 맞지 않음 APK 재빌드, Split은 install-multiple 사용
INSTALL_FAILED_INSUFFICIENT_STORAGE (-4) 저장 공간 부족 앱·캐시를 정리해 공간 확보
INSTALL_FAILED_DUPLICATE_PERMISSION (-5) 다른 패키지가 이미 정의한 권한을 또 정의함 AndroidManifest.xml의 권한 이름 점검
INSTALL_FAILED_UPDATE_INCOMPATIBLE (-7) 설치된 앱과 서명이 다름 기존 앱 삭제 후 설치
INSTALL_FAILED_DEXOPT (-11) DEX 최적화·검증 실패 저장 공간 확인, 재부팅, 재빌드
INSTALL_FAILED_OLDER_SDK (-12) 기기 API 레벨이 앱의 minSdk보다 낮음 더 높은 API 기기 사용 또는 minSdk 조정
INSTALL_FAILED_TEST_ONLY (-15) 테스트 전용 APK를 일반 설치함 adb install -t <apk>
INSTALL_FAILED_VERIFICATION_FAILURE (-22) 설치 검증 실패 또는 시간 초과 재부팅 후 재시도, APK 무결성 확인
INSTALL_FAILED_VERSION_DOWNGRADE (-25) 설치된 앱보다 versionCode가 낮음 삭제 후 설치 또는 adb install -r -d (디버그 빌드)
INSTALL_FAILED_INTERNAL_ERROR (-110) 시스템 내부 오류 재부팅, adb logcat 확인
INSTALL_FAILED_USER_RESTRICTED (-111) 사용자 설정이나 제조사 정책으로 설치가 막힘 USB 설치 허용 설정과 화면 승인 확인
INSTALL_FAILED_NO_MATCHING_ABIS (-113) APK의 네이티브 라이브러리가 기기 ABI와 맞지 않음 ABI 확인, 맞는 에뮬레이터 이미지 사용

오류 코드를 읽고 원인별로 조치한 뒤 설치를 검증하는 4단계 흐름
INSTALL_FAILED 점검 흐름


주요 INSTALL_FAILED_... 오류별 원인 분석 및 해결

INSTALL_FAILED_UPDATE_INCOMPATIBLE (-7)

같은 패키지 이름의 앱을 업데이트하려면 서명이 같아야 합니다. 디버그 빌드와 릴리스 빌드의 서명 키가 다르거나, Play 스토어에서 설치한 앱 위에 로컬 빌드를 설치하려 할 때 주로 발생합니다. 기존 앱을 삭제하면 앱 데이터도 함께 사라지므로, 필요한 데이터가 있다면 먼저 백업하세요.

📌 해결 단계
  1. 기존 앱 제거: 서명이 다른 기존 앱을 먼저 제거합니다.
    BASH
    adb uninstall <package_name>
  2. 새로운 APK 설치: 기존 앱이 제거된 후, 새로운 APK 파일을 설치합니다.
    BASH
    adb install <apk_path>

INSTALL_FAILED_NO_MATCHING_ABIS (-113)

이 오류는 APK에 포함된 네이티브 라이브러리(.so 파일)가 대상 기기나 에뮬레이터의 CPU 아키텍처(ABI: Application Binary Interface)를 지원하지 않을 때 발생합니다. 예를 들어 x86용 라이브러리만 담긴 APK를 ARM 기기에 설치하거나, 반대로 arm64 라이브러리만 담긴 APK를 x86 에뮬레이터에 설치하면 발생합니다.

📌 해결 단계
  1. 대상 기기/에뮬레이터 ABI 확인: 아래 명령으로 기기가 지원하는 ABI를 확인합니다.
    BASH
    adb shell getprop ro.product.cpu.abilist
  2. build.gradle 설정 확인 및 수정: 앱의 build.gradle 파일(모듈 수준)에서 ndk.abiFilters 설정을 확인하여 필요한 ABI가 포함되어 있는지 확인합니다.
    GRADLE
    // build.gradle (Module: app) 예시
    android {
        // ...
        defaultConfig {
            // ...
            ndk {
                // 이 앱이 지원하는 ABI 목록을 정의합니다.
                // 대상 기기의 ABI와 일치하는지 확인하세요.
                abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
            }
        }
        // ...
    }
    이 설정은 APK에 어떤 ABI의 네이티브 라이브러리를 넣을지 결정합니다. ABI를 많이 포함할수록 APK가 커지므로 필요한 것만 선택합니다. 서드파티 라이브러리가 특정 ABI만 제공하는 경우에도 같은 오류가 날 수 있으니 의존성의 지원 ABI를 함께 확인하세요. 자세한 내용은 Android ABI 문서를 참고하세요.
  3. 에뮬레이터 이미지 변경: 에뮬레이터라면 APK가 지원하는 ABI와 같은 시스템 이미지를 사용합니다. Apple Silicon Mac에서는 arm64 이미지가 기본입니다.

INSTALL_FAILED_INSUFFICIENT_STORAGE (-4)

이 오류는 기기에 앱을 설치할 충분한 저장 공간이 없을 때 발생합니다. 단순히 앱 크기뿐만 아니라, 앱 설치 과정에서 필요한 임시 파일, 캐시 데이터 등도 저장 공간을 차지합니다.

✅ 해결 체크리스트
  • 기기 저장 공간 확인: 기기의 설정에서 사용 가능한 저장 공간을 확인합니다.
  • 불필요한 앱 제거: 사용하지 않는 다른 앱을 제거하여 공간을 확보합니다.
  • 캐시 데이터 및 임시 파일 삭제: 기기의 설정에서 앱별 캐시를 지우거나, 시스템 캐시를 정리하여 공간을 확보합니다.
  • adb shell pm clear <package_name>: 특정 앱의 데이터를 지워 공간을 확보합니다. 해당 앱의 데이터가 사라집니다.
  • adb shell df /data: 데이터 파티션의 남은 공간을 확인합니다.

INSTALL_FAILED_VERSION_DOWNGRADE (-25)

이 오류는 설치하려는 앱의 버전 코드가 현재 기기에 설치된 앱의 버전 코드보다 낮을 때 발생합니다. Android 시스템은 일반적으로 이전 버전의 앱으로 다운그레이드하는 것을 허용하지 않습니다.

📌 해결 단계
  1. 앱 버전 코드 확인: 설치하려는 APK의 versionCode가 기기에 설치된 앱보다 높은지 확인합니다. adb shell dumpsys package <package_name> | grep versionCode로 설치된 값을 볼 수 있습니다.
  2. 다운그레이드 허용 설치: 디버그 가능한(debuggable) 빌드라면 adb install -r -d <apk_path>로 데이터를 유지한 채 낮은 버전을 설치할 수 있습니다. 릴리스 빌드에서는 거부될 수 있습니다.
  3. 기존 앱 제거: 위 방법이 안 되면 기존 앱을 먼저 제거합니다. 앱 데이터는 사라집니다.
    BASH
    adb uninstall <package_name>
  4. APK 설치: 제거 후 원하는 버전의 APK를 설치합니다.

INSTALL_FAILED_OLDER_SDK (-12)

이 오류는 대상 기기의 Android 버전(API 레벨)이 앱이 요구하는 minSdk보다 낮을 때 발생합니다. 앱이 특정 API 레벨 이상의 기능을 사용하도록 빌드되었지만, 해당 기능을 지원하지 않는 하위 버전의 Android 기기에 설치하려 할 때 나타납니다.

📌 해결 단계
  1. 대상 기기 API 레벨 확인: 대상 기기의 Android 버전을 확인합니다. (예: 설정 > 휴대전화 정보 > Android 버전)
  2. 앱의 minSdk 설정 확인: 앱의 build.gradle 파일(모듈 수준)에서 minSdk 버전을 확인합니다.
    GRADLE
    // build.gradle (Module: app) 예시
    android {
        // ...
        defaultConfig {
            applicationId "com.example.myapp"
            minSdk 24 // 이 앱이 실행될 수 있는 최소 API 레벨
            targetSdk 34 // 앱이 대상으로 하는 API 레벨 (Android 14)
            versionCode 1
            versionName "1.0"
            // ...
        }
        // ...
    }
  3. 해결 방법 선택:
    • minSdk 조정: 앱의 minSdk를 대상 기기의 API 레벨과 같거나 낮게 설정합니다. 단, 이 경우 앱이 사용하는 기능 중 minSdk보다 높은 API 레벨에서만 지원되는 기능이 있다면 문제가 발생할 수 있습니다.
    • 더 높은 API 레벨 기기/에뮬레이터 사용: 앱의 minSdk 요구사항을 충족하는 더 높은 API 레벨을 가진 기기나 에뮬레이터를 사용합니다.

INSTALL_FAILED_USER_RESTRICTED

사용자 설정이나 제조사 정책 때문에 설치가 거부됐다는 뜻입니다. 기기 화면에 설치 승인 팝업이 뜨는 기기에서는 팝업을 제때 누르지 못했거나 거부한 경우가 많고, 업무용 프로필 정책이 설치를 막는 경우도 있습니다. Xiaomi(MIUI/HyperOS) 기기에서는 개발자 옵션의 "USB를 통한 설치" 항목이 꺼져 있어서 자주 발생합니다.

⚠️ MIUI/HyperOS 기기 특이사항

Xiaomi 기기에서는 "USB를 통한 설치"와 "USB 디버깅(보안 설정)" 항목을 켜려면 Xiaomi 계정 로그인이 필요한 경우가 있습니다. 기기 모델과 OS 버전에 따라 메뉴 이름과 조건이 다릅니다.

📌 해결 단계
  1. 개발자 옵션 및 USB 디버깅 활성화:
    • 기기 설정에서 "개발자 옵션"을 활성화합니다. (보통 "빌드 번호"를 여러 번 탭하여 활성화)
    • 개발자 옵션 내에서 "USB 디버깅"을 활성화합니다.
    • "USB를 통한 설치"(Install via USB) 또는 "USB 디버깅(보안 설정)" 항목이 있으면 함께 활성화합니다.
  2. 기기 화면 확인: 설치를 시작하면 기기에 승인 팝업이 뜨는지 지켜보다가 바로 허용합니다. 화면이 잠겨 있으면 팝업을 놓치기 쉽습니다.
  3. 재시도: USB 케이블을 다시 연결하고 adb kill-server 후 adb start-server로 서버를 재시작한 다음 설치를 다시 시도합니다.
  4. 업무용 프로필·제한 정책 확인: 회사 관리 기기라면 관리자가 설치를 제한했을 수 있습니다.

adb install은 "알 수 없는 출처의 앱 설치 허용" 설정과 무관하게 동작합니다. 이 설정은 파일 관리자 등 기기 안에서 APK를 직접 열어 설치할 때만 필요합니다.


기타 INSTALL_FAILED_... 오류 및 일반적인 해결책

  • INSTALL_FAILED_INVALID_APK: APK 파일이 손상됐거나, Split APK 세트가 불완전하거나 서로 다른 빌드의 파일이 섞였을 때 발생합니다. APK를 다시 빌드하고, Split APK는 adb install-multiple로 한 번에 설치합니다.
  • INSTALL_FAILED_TEST_ONLY: 테스트 전용으로 빌드된 패키지를 adb install -t 옵션 없이 설치하려고 할 때 발생합니다.
    BASH
    adb install -t <apk_path>
  • INSTALL_FAILED_DEXOPT: 앱이 DEX 파일을 검증하는 데 실패했을 때 발생합니다. 저장 공간 부족이나 손상된 APK가 원인인 경우가 많습니다. 저장 공간을 확보하고 다시 빌드해 보세요.
  • INSTALL_FAILED_DUPLICATE_PERMISSION: 설치하려는 앱이 이미 시스템에 존재하는 다른 패키지에 의해 정의된 권한을 정의하려고 할 때 발생합니다. AndroidManifest.xml에서 권한 정의를 검토하고, 충돌하는 권한이 없는지 확인합니다.
  • INSTALL_FAILED_INTERNAL_ERROR: 시스템 PackageManager 내부에서 원인이 분류되지 않은 오류가 났을 때 나타납니다. 기기를 재부팅하고, adb logcat으로 같은 시각의 로그를 확인합니다.
  • INSTALL_FAILED_VERIFICATION_FAILURE: 설치 검증 프로세스가 시간 초과되거나 실패했을 때 발생합니다. 기기 재부팅, 저장 공간 확보, 또는 APK 파일의 무결성 확인이 필요할 수 있습니다.

적용 후 검증 및 재발 방지

앱 설치 실패 오류를 해결한 후에는 반드시 앱이 정상적으로 실행되는지 확인해야 합니다.

📌 검증 단계
  1. 앱 실행 확인: 기기에서 앱 아이콘을 찾아 탭하여 앱이 성공적으로 시작되는지 확인합니다.
  2. pm list packages 명령 사용: adb shell pm list packages | grep <package_name> 명령을 사용하여 앱이 시스템에 올바르게 설치되었는지 확인할 수 있습니다.
    BASH
    adb shell pm list packages | grep com.example.myapp
    정상적으로 설치되었다면 패키지 이름이 출력됩니다.
  3. 로그 모니터링: 앱 실행 중에도 adb logcat을 계속 모니터링하여 예상치 못한 오류나 경고 메시지가 없는지 확인합니다.

재발 방지

  • 테스트 기기 정리: 저장 공간을 주기적으로 비우고, 쓰지 않는 예전 빌드를 삭제합니다.
  • 서명 키 통일: 팀원과 CI가 같은 디버그 키스토어를 쓰도록 맞추면 UPDATE_INCOMPATIBLE이 줄어듭니다. 서명 방식은 앱 서명 문서를 참고하세요.
  • 버전 관리 철저: versionCode와 versionName을 체계적으로 관리하여 INSTALL_FAILED_VERSION_DOWNGRADE와 같은 오류를 방지합니다.
  • 테스트 환경 일관성 유지: 개발 및 테스트에 사용하는 에뮬레이터 또는 실제 기기의 Android 버전, ABI 등을 일관되게 유지하여 INSTALL_FAILED_NO_MATCHING_ABIS나 INSTALL_FAILED_OLDER_SDK와 같은 환경 의존적인 오류를 줄입니다.
  • 스크립트에서는 출력 확인: 자동화 스크립트에서는 종료 코드만 믿지 말고 출력에 Success가 있는지 확인합니다. adb 버전에 따라 실패해도 종료 코드가 0일 수 있습니다.

FAQ

Q. adb install 명령이 "Success"라고 뜨는데 앱이 보이지 않거나 실행되지 않아요.

A. adb install 명령의 출력은 설치 프로세스 자체의 성공 여부만 나타낼 뿐, 앱이 정상적으로 실행될 준비가 되었음을 의미하지는 않습니다. 다음을 확인하세요:

  • 앱 런처 확인: 모든 앱 목록에서 앱 아이콘을 찾아보세요.
  • adb logcat 확인: 앱 실행 시 발생하는 오류 메시지가 있는지 확인합니다.
  • adb shell pm list packages: 앱의 패키지 이름으로 설치 여부를 다시 확인합니다.
  • Split APK 문제: Split APK를 설치하는 경우, 모든 구성 요소가 올바르게 설치되었는지 확인해야 합니다. adb install-multiple 명령을 사용하거나, bundletool을 통해 apks 파일을 생성하고 adb install-apks로 설치해야 할 수 있습니다.

Q. 개발자 옵션과 USB 디버깅이 활성화되어 있는데도 adb devices에 기기가 unauthorized로 표시됩니다.

A. 기기에서 이 컴퓨터의 USB 디버깅 권한을 승인하지 않았을 때 나타납니다.

  • 기기 화면 확인: USB 케이블 연결 시 기기 화면에 "USB 디버깅 허용" 팝업이 뜨는지 확인하고, "항상 이 컴퓨터에서 허용"을 체크한 후 "확인"을 탭합니다.
  • ADB 서버 재시작: adb kill-server 후 adb start-server 명령으로 ADB 서버를 재시작해 보세요.
  • 자세한 내용은 ADB unauthorized 오류 원인과 해결을 참고하세요.

Q. INSTALL_FAILED_USER_RESTRICTED 오류가 계속 발생하는데, Xiaomi 기기가 아닙니다.

A. Xiaomi 기기가 아니더라도, 특정 OEM 기기나 커스텀 ROM에서는 보안 정책으로 인해 유사한 제한이 있을 수 있습니다.

  • 기기 안에서 설치하는 경우: 파일 관리자 등으로 APK를 열어 설치한다면 해당 앱에 "알 수 없는 앱 설치" 권한이 있는지 확인합니다.
  • 기기 재부팅: 단순한 일시적 오류일 수 있으므로 기기를 재부팅해 보세요.
  • adb logcat 상세 분석: adb logcat을 통해 PackageManager나 Security 태그와 관련된 로그를 자세히 살펴보면 추가적인 힌트를 얻을 수 있습니다.

Q. INSTALL_FAILED_INTERNAL_ERROR는 어떻게 해결해야 하나요?

A. 원인이 분류되지 않은 시스템 오류라 코드만으로는 원인을 알기 어렵습니다.

  • 기기 재부팅: 가장 먼저 시도해야 할 방법입니다.
  • adb logcat 확인: 오류 시점의 PackageManager, installd 로그에 구체적인 예외가 남아 있는 경우가 많습니다.
  • 다른 기기/에뮬레이터에서 시도: 문제가 특정 기기에서만 발생하는지 확인하기 위해 다른 환경에서 설치를 시도해 봅니다.
  • APK 파일 무결성 확인: APK 파일이 손상되지 않았는지 다시 확인합니다.

참고 자료