APK Downloader
·14 min read

APK Stuck on 'Installing…': PackageInstaller Sessions and a Layer-by-Layer adb Diagnosis

The spinner keeps turning, nothing fails, nothing finishes. Since Android 5.0 an install is a stateful PackageInstaller session with separate create, write, commit, and post-commit stages - and each one stalls for a different reason. Here are the mechanism tables, runnable adb commands, a six-step path, an error-code lookup, and an FAQ.

androidapkpackage installeradbtroubleshootinggptoapk

The spinner has been turning for ten minutes. The progress bar does not move, no error appears, and the cancel button seems to do nothing. Most people reboot, clear the installer cache, tap Install again, and hope. Sometimes it works; often it turns into a loop. The reason this class of problem is so hard to self-diagnose is that the UI gives you exactly one piece of information - a spinner - while underneath there is a stateful install pipeline that has stopped at a stage the system has neither declared successful nor reached the point of being able to report an error to the user.

This guide skips the generic 'clear cache, try another file' advice and opens up the Android install session instead: what stages it has, which component owns each one, what evidence a stall leaves behind, and how to use adb to pin the stall to a specific layer. Every command below can be copied and run as-is.

First: is it the download, the verification, or the install session?

Classify before you troubleshoot, because these three look almost identical on screen but need completely different responses. If the file has not landed on the device at all, you are looking at a download problem - see the layer-by-layer guide to a downloaded APK that is nowhere to be found or the interrupted download and resume walkthrough. If the browser said the download completed and the file then vanished, follow the disappearing download file path. The table below applies only when the file is already on the phone and you have tapped it to start installing.

What the screen showsMain background componentNormal durationA stall usually means
Download notification stuck at 99%DownloadManager or the browser downloaderSeconds to minutesFile never fully landed; nothing to do with install sessions
'Checking…' or 'Scanning…'Package verifier, Play Protect, OEM scanner1-30 secondsThe verifier is waiting on a network verdict and has timed out
'Installing…' with a spinnerPackageInstaller session plus PackageManagerService2-60 secondscreate, write, or commit is blocked, or post-commit dexopt is stuck
'Optimising app…'dex2oat / ART compilationSeconds to minutesCompiling a large package without enough space or CPU headroom
Bar completes, then straight back to the home screenInstaller Activity finishingInstantIt actually failed and the UI swallowed the error; logcat will have it

A practical rule: if you can still see a download progress notification, you have not entered an install session yet. PackageInstaller only starts working after you open the APK and the install confirmation sheet appears.

What an install session actually is: one install, four stages

Starting with Android 5.0 (API 21), the system models 'install an app' as a session via the PackageInstaller API. A session has a unique ID, has state, accepts data across multiple writes, and can be abandoned. The design exists mainly for split APKs and large games: open a session, stream base.apk and each split into it, then hand the whole thing to the system in one commit.

This matters because it explains why the spinner can sit there with nothing apparently happening. On many builds the spinner represents a wait for batch processing after commit, long after the write phase has finished.

Stageadb equivalentInternal system actionTypical symptom when it stalls
createpm install-create -S <bytes>Allocate a session ID, reserve a temp directory under /dataUsually fails outright on low space; rarely spins
writepm install-write -S <bytes> <id> base.apkStream APK bytes into the session staging areaSlow on large packages, /data full, USB transfer dropped
commitpm install-commit <id>Submit to PackageManagerServiceThe most common spin point: verification, signature comparison, permission grants all happen here
post-commitNo direct commandParse the manifest, run dexopt, broadcast PACKAGE_ADDED'Optimising app' that never finishes
abandonpm install-abandon <id>Drop the session and reclaim staged filesStale sessions keep occupying storage

adb install is not a separate mechanism; it is this same create → write → commit chain wrapped into a single command. That gives you a useful bisection tool: if adb install succeeds but the tap-to-install path hangs, the fault is almost certainly in the installer UI, the verifier, or an OEM customisation layer, not in the package. If adb install hangs at the same point, look at storage and dexopt instead.

Five root causes and the evidence each one leaves

Here are the usual suspects and their signatures. The six-step path in the next section simply eliminates these one by one.

Root causeMechanismObservable signalLocating command
/data partition short on spaceSession staging and dexopt output both need room; the system reserves more than the APK sizeINSTALL_FAILED_INSUFFICIENT_STORAGE or a dex2oat write failure in logcatadb shell df -h /data
Stale or wedged sessionA previous install was killed before commit or abandon; the installer keeps waitingdumpsys shows a session record that has not changed for a long timeadb shell dumpsys package and look for the session section
Verifier blocked on the networkAt commit the system queries a cloud verdict for the certificate and risk; weak network or server timeouts hang itverification timeout or VERIFICATION_FAILURE in logcatadb logcat -s PackageManager:V
Signature or version conflictSame package name with a different signer, or a downgrade; fully evaluated only at commitINSTALL_FAILED_UPDATE_INCOMPATIBLE or a signature mismatchadb logcat -s PackageInstallerSession:V
Split or ABI mismatchbase.apk missing, or a split that does not match the device architectureINSTALL_FAILED_MISSING_SPLIT, or an immediate crash after installadb shell getprop ro.product.cpu.abi
OEM background limits, installer killedBattery policy reaps the installer process, or background installs are restrictedSpinner then abrupt return to the home screen with no erroradb shell dumpsys activity and grep for installer

One counter-intuitive detail about storage: the system generally needs two to three times the APK size in free space, because it must hold the staged session copy, the installed APK, and the dexopt output at the same time. A 1.2 GB game package on a phone with 1.5 GB free will very often hang at commit or at the optimisation step. For that class of problem, the ordering in reclaiming space from bloated APKs and storage still full after uninstalling apps applies directly.

Before you start: setup and read-only sampling

Attach the device and take a read-only sample first. Do not clear data or change settings before you have evidence. These commands work in adb on macOS, Linux, and Windows; on Windows, put the pipe inside the remote shell, for example adb shell "dumpsys package | grep -i session".

adb devices
adb shell getprop ro.build.version.release
adb shell getprop ro.build.version.sdk
adb shell getprop ro.product.cpu.abi
adb shell df -h /data
adb shell df -h /cache
adb shell dumpsys package | grep -i -A 30 "install session"
adb logcat -d -s PackageManager:V PackageInstallerSession:V | tail -80

Write down four values: Android version, CPU ABI, free space on /data, and whether an unfinished session exists. Those four determine which branch you take next. If USB debugging is not enabled yet, work through offline installation setup first. If the confirmation sheet never appears at all, check how unknown-source permission changed across Android versions.

The six-step diagnosis

Step 1: confirm a session actually exists

Clear the log buffer, then trigger the install once, so everything you capture belongs to this attempt.

adb logcat -c
adb logcat -s PackageManager:V PackageInstaller:V PackageInstallerSession:V &

In a second terminal, tap the APK, then watch the log window. If there is not even a createSession-style record, the installer never opened a session - the problem is in permissions or the UI layer, not the install chain. If a session ID appears but no commit follows, the session is suspended. dumpsys field names vary by Android version, so combine adb shell dumpsys package | grep -i session with adb shell cmd package help to see the subcommands your build supports.

Step 2: check space properly, not just the 'GB free' number

adb shell df -h /data
adb shell du -sh /data/app /data/local/tmp 2>/dev/null
adb shell pm trim-caches 1G

df gives the partition totals, du shows who is consuming them, and pm trim-caches asks the system to reclaim some cache without touching your app data. If /data has less than twice the APK size available, clean up before retrying instead of tapping Install repeatedly. This step also surfaces leftover session staging files.

Step 3: capture the commit-stage error code

This is the highest-information step. Keep the log listener running, trigger the install again, and look specifically for these markers.

adb logcat -s PackageManager:V PackageInstallerSession:V | grep -i -E "install|verify|dexopt|failed|timeout"
logcat keywordMeaningNext move
INSTALL_FAILED_INSUFFICIENT_STORAGENot enough spaceBack to Step 2; free two to three times the package size
INSTALL_FAILED_UPDATE_INCOMPATIBLESame package name, different signer, or a downgradeUninstall the old build, or re-sign and reinstall
INSTALL_FAILED_VERIFICATION_FAILUREVerifier rejected it or timed outStep 6: check network and verifier state
INSTALL_FAILED_DEXOPTART compilation failedSpace, SELinux, or a damaged package
INSTALL_FAILED_MISSING_SPLITIncomplete split setStep 5
No failure at all, just a long commitWaiting on an external verdict or a suspended processStep 4: replay the session manually

If the log shows a successful install broadcast but there is no icon on the home screen, you are past the install session entirely - go to installed but no app icon in the launcher. If it opens and crashes immediately, see installs fine but crashes on launch.

Step 4: replay the session manually to split the stall point

This is the most direct test: bypass the installer UI and run each stage with adb, then see which command stops responding.

adb push app.apk /data/local/tmp/app.apk
SIZE=$(stat -f %z app.apk)
adb shell pm install-create -r -S $SIZE
adb shell pm install-write -S $SIZE <SESSION_ID> base.apk /data/local/tmp/app.apk
adb shell pm install-commit <SESSION_ID>
adb shell pm install-abandon <SESSION_ID>

A few notes. stat -f %z is the macOS form; on Linux use stat -c %s. install-create prints a number - that is the <SESSION_ID> to substitute. The second argument to install-write is the name inside the session; for the base package use base.apk. Only run the final install-abandon when a session failed or was left behind; do not run it after a successful commit.

If install-write hangs, look at the USB link and /data writes. If install-commit hangs, look at the verifier and the signature. If all three return immediately with success, the stall is in the installer UI or the OEM layer, and adb install -r app.apk is a perfectly good way to deliver the app.

Step 5: submit split APKs in the right order

Modern apps exported from a store are frequently not one file but a base plus several splits. Installing only the base with adb install may succeed yet leave resources missing, or hang at commit.

adb shell getprop ro.product.cpu.abi
adb shell getprop ro.product.cpu.abilist
adb install-multiple base.apk split_config.arm64_v8a.apk split_config.xxhdpi.apk
adb shell pm path com.example.app

The rules are simple: base.apk must come first; submit only architecture splits matching ro.product.cpu.abi; pick one density split. For an already installed package, adb shell pm path <package> shows which splits the system actually accepted, which is a good way to verify the set you submitted was complete.

Step 6: separate the verifier from OEM restrictions

adb shell settings get global package_verifier_enable
adb shell settings get secure install_non_market_apps
adb shell dumpsys package com.google.android.gms | grep -i verify
adb shell dumpsys activity | grep -i installer

package_verifier_enable reports whether system-level package verification is on; install_non_market_apps corresponds to the unknown-sources switch. Use these for diagnosis only. Turning off security scanning permanently to install one APK is a bad trade: if the log clearly says verification timeout, the sane response is to switch to a stable network, wait briefly, and retry, or to deliver through the adb chain in Step 4. If dumpsys activity shows the installer process being reaped, check that vendor's battery whitelist and background-popup restrictions.

Three real scenarios, end to end

Scenario A: ten-minute spinner, logcat says verification timeout. Step 1 confirms the session was created and written; Step 3 catches the timeout keyword; Step 6 confirms the verifier is enabled. Fix: retry on a stable network, and if it still hangs, deliver with the three adb commands from Step 4. Do not tap Install repeatedly - that stacks multiple waiting sessions.

Scenario B: adb install returns Success, but the app is absent from the launcher. You are past the install session; this is a launcher visibility problem. Go straight to installed but no app icon. If the installed app then causes unusual battery drain, see diagnosing battery drain after an APK install.

Scenario C: a large game package, apparently enough space, stuck on 'Optimising app'. Re-estimate against the two-to-three-times rule from Step 2, check for a dex2oat write failure in Step 3, and verify the OBB and split set in Step 5. Storage fragmentation is common here, and the sequence in slimming down APK files to free storage applies directly.

Mistakes worth avoiding

  • Tapping Install again and again. Each tap can open a new session. Queued sessions make the spinner longer and consume more /data staging space.
  • Deleting directories under /data/app directly. Impossible without root, and on rooted devices it tends to leave PackageManagerService records behind, which makes later installs more likely to report signature conflicts.
  • Permanently disabling all security scanning for one package. It converts a one-off verification timeout into a lasting risk. If you do change the verifier state, restore it afterwards.
  • Forcing `pm install -r` over a differently signed package. -r only handles an existing build with the same signer; across signers you must uninstall first, otherwise you get UPDATE_INCOMPATIBLE.
  • Treating a slow download as a stalled install. If the download notification is still active, the direction is the opposite one: solve the landing problem first, using the same layered approach as diagnosing download throttling.

FAQ

Why does the spinner keep turning without ever reporting an error?

Because the system has not reached a stage where it can produce a verdict. Verification, signature comparison, and dexopt after commit are asynchronous; as long as an external verdict has not returned, the installer stays in a waiting state. The clue is usually already in logcat - the UI simply does not translate it for you.

Does rebooting the phone fix it?

It helps with stale sessions and a killed installer process, because a reboot clears uncommitted in-memory session state. It does nothing for low storage, signature conflicts, or missing splits. Prefer Step 1 to confirm session state before deciding to reboot.

Do adb install and tap-to-install use the same flow?

Underneath, yes - the same PackageInstaller session. The difference is the entry point: adb calls create/write/commit directly, while tapping goes through an installer Activity and the package verifier. That is exactly why comparing the two outcomes narrows the search so quickly.

Does a stale session keep occupying storage?

Yes, until it is committed or abandoned. Staged files for an uncommitted session live under /data, and while a reboot normally clears the in-memory record, the written temporary files are not always reclaimed immediately. pm install-abandon <SESSION_ID> from Step 4 is the clean way to finish.

Why do split APKs stall more often?

Because commit must validate signature, version, and architecture consistency across the base and every split at once. If any piece is missing or does not match the device ABI, commit hangs or fails. Read ro.product.cpu.abi first and submit in the Step 5 order; that avoids most of these cases.

Does verification failure mean the file was tampered with?

Not necessarily. The marker covers both a genuine signature or hash mismatch and a verifier network timeout folded into the same result class. The deciding evidence is an integrity check on the file itself, not this one log line.

What happens if I keep tapping Install while it is stuck?

In most builds it creates another session and queues it, lengthening the spinner and consuming more /data staging space. The right move is adb logcat -c, a single trigger, a full capture of the chain, and an install-abandon to clean up.

Wrap-up

Treat 'Installing…' as a pipeline you can take apart and the diagnosis gets a fixed order: confirm you are actually in the install stage, check space and session state, capture the commit-stage error code, replay create/write/commit when needed, verify the split set, and only then consider the verifier and OEM limits. Those six steps locate the vast majority of spinner problems at a specific layer instead of leaving you to reboot and hope.

Further reading: before installing, unknown-source permission and offline installation setup; after installing, no app icon, crashes on launch, and battery drain; on the storage side, still full after uninstalling and reclaiming bloated APK space.