How do I run an adb shell command?

Switch on developer options and USB debugging on the phone, plug it in, then run adb shell from a machine with platform-tools installed — or run adb shell on its own to get an interactive prompt and type the command without the prefix. If the command produces binary output, such as a screenshot, use adb exec-out instead of adb shell: the plain shell service attaches a terminal, which rewrites newline bytes and corrupts the data.

Do adb shell commands need root?

Not the ones on this reference. They run as the shell user, which can manage packages for its own Android user, read most dumpsys services, write the settings provider, inject input and read shared storage. Root is only needed for things this reference deliberately avoids — reading another app's private data (except through run-as on a debuggable build), writing system partitions, or reading /data/anr directly.

Why does the output look different on my phone?

Either the Android version or the manufacturer. Some flags and fields arrived in a specific release, and those are noted per command. The rest is OEM patching, which hits dumpsys hardest: a dump is debug output whose text is whatever the service author last printed, and manufacturers change it and backport their changes. Read fields by name rather than by position, and treat an unfamiliar shape as a difference rather than as a failure.

Can I run this from a browser instead of a terminal?

For many commands, yes — the Web ADB tools on this site talk to a phone over WebUSB from a Chromium-based desktop browser, with no SDK installed and nothing uploaded. Each page links to the tool that runs its command, when one exists. Two limits are worth knowing: only one program can hold the ADB interface at a time, so a desktop adb server has to be stopped first, and adb forward and adb reverse cannot work in a browser at all.

pm install

changes the device

Installs one APK that is already on the device, which is what `adb install` does under the hood.

Command: adb shell pm install
Commands: Packages (pm)
Risk: changes the device

Syntax

pm install [-r] [-g] [-d] [-t] <path on device>

Flags and arguments

Token	Meaning
-r	Replace an existing installation instead of failing.
-g	Grant every runtime permission at install time.
-d	Allow a version downgrade. The app's existing data was written by the newer build and may not be readable by the older one.
-t	Allow an APK marked as test-only.

Examples

```
pm install -r /data/local/tmp/app.apk
```
Install or update from a file already pushed to the device.
```
pm install -r -g /data/local/tmp/app.apk
```
Install and pre-grant runtime permissions, so no dialogs appear on first run.
```
rm /data/local/tmp/app.apk
```
The step people forget: the staged copy stays on the phone otherwise.

Reading the output

Sample output

Success

`Success`, or a `Failure [INSTALL_FAILED_…]` naming the reason. The bracketed token is the part to search for — the same failure reaches you in several shapes (`Failure [CODE]`, `Failure [CODE: explanation]`, `Error: CODE`, or a Java exception trace), so look for the `INSTALL_FAILED_` or `INSTALL_PARSE_FAILED_` token anywhere in the text rather than for a particular sentence.

Output fields

Field	Meaning
Success	The package is installed.
INSTALL_FAILED_ALREADY_EXISTS	It is already installed; `-r` replaces it.
INSTALL_FAILED_VERSION_DOWNGRADE	Older than what is installed; `-d` allows it, with the data caveat.
INSTALL_FAILED_UPDATE_INCOMPATIBLE	A different signing certificate from the installed copy.
INSTALL_FAILED_INSUFFICIENT_STORAGE	Not enough space.
INSTALL_FAILED_MISSING_SPLIT	This APK is one of a split set; install the whole set.

What access it needs

An authorised `adb` connection, plus one thing the command cannot check for you: the phone has to be able to read the file you named. That is why `/data/local/tmp/` is the conventional staging directory, and why an APK left somewhere the shell user cannot reach fails for reasons that have nothing to do with the package inside it. Neither root nor `su` is required, and `adb root` is unavailable on a production build anyway. Two more gates sit past the access check and are worth knowing before blaming the APK. The device's package verifier, Play Protect included, can reject an install outright — the `disableVerifier` remedy in this package's error table exists for precisely that case. And some installs raise a prompt on the handset itself, which is why `unlockDevice` is a remedy at all: a locked screen can hold an install open until it gives up.

Failure messages, decoded

Message	Meaning
Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE]	The installed copy was signed with a different key. No flag helps: this package's preflight names it as the one outcome knowable in advance, and the cure is removing the installed app, data included, before installing again. The exception is an APK carrying a v3 rotation lineage descended from the installed certificate, which installs without complaint.
Failure [INSTALL_FAILED_VERSION_DOWNGRADE]	The APK's version code sits below what is already there. `-d` permits it, and the caveat is substantive rather than ceremonial: the data on the phone was written by the newer build and the older one may be unable to read it, so clearing that app's data is sometimes the only way to get it running afterwards.
Failure	A bare word on its own line, with no bracket and no code — old builds print this, and it leaves nothing to search for. `recognizeInstallOutcome` still classifies it as a failure rather than guessing, because an install that printed this installed nothing. Re-run with both streams captured before drawing any conclusion about why.
Exception occurred while executing 'install': java.lang.SecurityException:	One of the five shapes the same family of failure arrives in. The token you want is never in this line — it is in the trace beneath, if it is anywhere — which is why the recogniser sweeps the whole text for an `INSTALL_FAILED_` or `INSTALL_PARSE_FAILED_` token instead of matching a sentence.

What it changes, and the way back

Installing replaces the app that is there. With `-d` a downgrade is allowed, and app data written by the newer version may not load in the older one — that combination can leave an app broken until its data is cleared. Nothing else here is destructive: the way back is to install the version you had, or to uninstall.

Version and vendor notes

A path is a device path. The APK has to be on the phone first, which is why the desktop `adb install` pushes it for you.
For a split app — a base plus `split_config.*.apk` files — this command cannot help: use an install session (`pm install-create`).

We have a UI for this

APK Installer runs this command over USB and parses what comes back — a Chromium browser, no SDK, nothing uploaded.

Open APK Installer

Related commands

Commands that turn up in the same session as pm install.

Command	What it does
pm install-create	Opens an install session so several APKs — a base plus its splits — are installed as one atomic unit.
pm uninstall	Removes a package, or removes it for one Android user only — which is how a preinstalled app is disposed of without root.
pm path	Prints the absolute paths of the APK files that make up an installed package.
rm	Deletes a file or a directory tree on the device.

More Packages (pm) commands

Command	What it does
pm list packages	Lists installed packages, optionally with the APK path, uid, version code and installer.
pm disable-user	Switches a package off for one Android user without removing it — the reversible alternative to uninstalling.
pm clear	Wipes an app's data — or, on Android 13 and later, only its cache.
pm trim-caches	Asks the system to drop cached files until the given amount of free space exists.

Checked against AOSP, toybox and kernel sources while writing the parsers behind our Web ADB tools. Where a behaviour genuinely varies by Android version or manufacturer, this page says so instead of giving a number that would be wrong on half the phones out there.