Installing And Managing Apps

Installing and Managing Apps — adb install and pm

App lifecycle from the host. adb install ships an APK; pm is the on-device PackageManager front-end that lists, paths, clears, enables/disables, and grants permissions. The most common subtle bug in test scaffolding is using am force-stop to "reset" an app between tests — that command kills the process but leaves SharedPreferences, the Room DB, and files on disk. The hermetic equivalent is pm clear.

When to use this skill

• The user wants to install an APK from the host or push a debug build between every test run.
• The user asks "how do I reset the app's state between tests?" or sees stale data carry over from one test to the next.
• The user hits INSTALL_FAILED_VERSION_DOWNGRADE, INSTALL_FAILED_USER_RESTRICTED, or signature mismatch errors.
• The user wants to grant all runtime permissions at install (-g), or grant/revoke a single permission post-install.
• The user wants to list only third-party packages, find an APK on disk, or dump a Baseline Profile.

When NOT to use this skill

• The user wants to actually run instrumented tests against the installed app — use ../../tests/running-instrumented-tests-via-adb/SKILL.md.
• The user wants to choose a device or wait for boot — use ../../devices/connecting-to-devices/SKILL.md.
• The user wants the architecture / environment / authentication picture — use ../../architecture/understanding-adb-architecture/SKILL.md.

Prerequisites

• A connected device with state device (see ../../devices/connecting-to-devices/SKILL.md).
• The APK(s) signed with a debug or release key the developer controls.
• For test APKs, the manifest sets android:testOnly="true" (Gradle does this for androidTest builds) and install requires -t.
• For runtime permissions, the device runs API 23+.

Workflow

• 1. Install with the right flags. From pm install (and the adb install wrapper) options table:

  Flag	Meaning
  -r	"Reinstall an existing app, keeping its data." Required when the package is already installed; without it adb install returns INSTALL_FAILED_ALREADY_EXISTS. CI scripts MUST always pass -r for repeat runs.
  -d	"Allow version code downgrade." Required when the new APK has a lower versionCode. Note: per adb help, restricted to debuggable packages on stock builds.
  -t	"Allow test APKs to be installed." Required for any APK whose manifest carries android:testOnly="true" (i.e. all Gradle androidTest builds).
  -g	"Grant all permissions listed in the app manifest." Best for hermetic test runs.
  -l	Forward-lock the application (legacy DRM). Almost never needed today.
  -s	Install on the SD card / external storage (when device supports it).
  --user <id>	Install for a specific user profile. Default: all users. current resolves to the foreground user.
  `--install-location 0	1
  -f	Install on internal system memory.
  -i <installer_pkg>	Tag the install with an installer package name.
  --fastdeploy	Patch-only install (only changed parts of the APK).
  --incremental / --no-incremental	Streamed install; requires APK Signature Scheme v4 sidecar .idsig. --wait blocks until full APK is available.

  Common recipes:

  adb install -r app-debug.apk                       # ordinary reinstall
  adb install -r -d app-debug.apk                    # allow downgrade
  adb install -r -t -g app-androidTest.apk           # test APK with all permissions granted
  adb install -r -d --user current app-debug.apk     # force foreground-user install

• 2. For split APKs use adb install-multiple. A modern App Bundle produces a base APK plus per-feature/per-config splits — adb install of just one fails:

  adb install-multiple -r -t -g \
    base-master.apk base-arm64_v8a.apk base-xxhdpi.apk

• 3. Reset app state between tests with pm clear. Do NOT use am force-stop for hermetic isolation.

  • am force-stop <pkg> "Force-stop everything associated with package." — kills processes only. SharedPreferences, Room/SQLite databases, files in /data/data/<pkg>, and cache persist.
  • pm clear <pkg> "Delete all data associated with a package." — wipes user data and cache. The next launch starts from a fresh-install state. For genuine hermetic isolation between tests (the default for instrumented suites), use pm clear. am force-stop is appropriate only when the explicit goal is to kill the process while preserving state (e.g. testing a "resume from killed" path).

  adb shell pm clear com.example.app

  Most pipelines wire this up via Test Orchestrator's clearPackageData instrumentation arg — see ../../tests/running-instrumented-tests-via-adb/SKILL.md.

• 4. List, find, and inspect packages with pm list packages and pm path.

  pm list packages [-f] [-d] [-e] [-s] [-3] [-i] [-u] [--user <id>] [<filter>]

  Flag	Meaning
  -f	"See associated file."
  -d	"Filter to only show disabled packages."
  -e	"Filter to only show enabled packages."
  -s	"Filter to only show system packages."
  -3	"Filter to only show third-party packages."
  -i	"See the installer for the packages."
  -u	"Include uninstalled packages."
  --user <id>	"The user space to query."

  Recipes:

  adb shell pm list packages -3 | sort                   # all sideloaded apps
  adb shell pm list packages -f com.example              # APK paths for matching pkgs
  adb shell pm path com.example.app                      # package:/data/app/.../base.apk
  adb shell dumpsys package com.example.app | head -200  # detailed install/permission info

• 5. Manage runtime permissions with pm grant / pm revoke (API 23+).

  "Grant a permission to an app. On devices running Android 6.0 (API level 23) and higher, the permission can be any permission declared in the app manifest."

  adb shell pm grant  com.example.app android.permission.CAMERA
  adb shell pm revoke com.example.app android.permission.CAMERA
  adb shell pm reset-permissions                         # reset every app to defaults

  Flagging -g at install time grants every manifest-declared runtime permission in one shot — preferred for hermetic test runs.

• 6. Enable / disable packages or specific components.

  adb shell pm disable com.example.app                       # whole package
  adb shell pm disable-user --user 0 com.example.app         # per-user disable (preserves data)
  adb shell pm enable  com.example.app
  adb shell pm enable  com.example.app/.MyTestActivity       # specific component

  Useful for forcing a known accessibility-service / IME state in tests, or for staging A/B comparisons by disabling rivals.

• 7. Uninstall correctly.

  pm uninstall [-k] [--user <id>] [--versionCode <vc>] <package>

  • -k "Keep the data and cache directories after package removal." Useful for upgrade-from-clean tests where the user data simulates an existing install.
  • --user <id> per-user removal.
  • --versionCode <vc> "Only uninstalls if the app has the given version code." Idempotent uninstall in CI scripts.

  adb uninstall com.example.app                       # equivalent to: pm uninstall <pkg>
  adb shell pm uninstall -k com.example.app           # uninstall but preserve data
  adb shell pm uninstall --user 0 com.example.app     # only from primary user

• 8. Dump a Baseline Profile when needed.

  "Starting in Android 7.0 (API level 24), the Android Runtime (ART) collects execution profiles for installed apps... adb shell cmd package dump-profiles <package> then adb pull /data/misc/profman/<package>.prof.txt." The doc warns: "It is only possible to retrieve the execution profile filename if you have root access to the file system, for example, on an emulator." On user builds without root, use androidx.benchmark Macrobenchmark to extract the profile programmatically.

• 9. Diagnose common install failures:

  Error	Cause	Fix
  INSTALL_FAILED_VERSION_DOWNGRADE	New APK's versionCode is lower than the installed one.	Add -d.
  INSTALL_FAILED_USER_RESTRICTED	Multi-user device: the install user (typically the secondary or work profile) blocks installs.	--user 0 or --user current; have the user disable "Install via USB" restriction in their profile.
  INSTALL_FAILED_UPDATE_INCOMPATIBLE (signature mismatch)	New APK signed with a different key than the installed one.	Uninstall first (adb uninstall <pkg>); resign with the same key.
  INSTALL_FAILED_TEST_ONLY	APK has android:testOnly="true" but -t was omitted.	Add -t (typical for app-androidTest.apk).
  INSTALL_FAILED_INVALID_APK (split APK only)	Tried to install one APK of a split set.	Use adb install-multiple.
  INSTALL_FAILED_INSUFFICIENT_STORAGE	Out of space.	adb shell df /data and cleanup.

• 10. Quote the shell correctly (Platform Tools 23+ rule). Verbatim from the adb page:

  "With Android Platform Tools 23 and higher, adb handles arguments the same way that the ssh(1) command does. ... adb shell setprop key 'two words' is now an error ... To make the command work, quote twice, once for the local shell and once for the remote shell, as you do with ssh(1). For example, adb shell setprop key \"'two words'\" works because the local shell takes the outer level of quoting and the device still sees the inner level of quoting." Same rule applies for any pm argument with spaces, special characters, or shell metacharacters.