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 trim-caches

changes the device

Asks the system to drop cached files until the given amount of free space exists.

Command: adb shell pm trim-caches
Commands: Packages (pm)
Risk: changes the device

Syntax

pm trim-caches <free space target>[K|M|G]

Flags and arguments

Token	Meaning
<target>	How much free space to aim for. The suffix is a power of 1024, so `512G` means 512 GiB — deliberately more than any phone has, i.e. "drop everything you consider disposable".

Examples

```
pm trim-caches 512G
```
Free every cache the system is willing to drop.
```
pm trim-caches 2G
```
Stop once there are 2 GiB free.

Reading the output

Nothing. Success is silence: the command waits for the platform to finish and returns without printing, and it never reports how much it freed — not even whether it freed anything. The only honest "you got N MB back" is to measure free space before and after with `df` or `dumpsys diskstats`. Anything printed at all is a refusal: an invalid suffix, a missing number, or an exception when the build did not grant the shell the permission this needs.

Output fields

Field	Meaning
(no output)	The trim ran. How much it freed is not reported.
Invalid suffix: …	The size argument was not understood.
Error: expected number at: …	The size argument was not a number.

What access it needs

An authorised `adb` connection, and nothing else: `packages/Shell/AndroidManifest.xml` on the `android16-release` branch declares `CLEAR_APP_CACHE`, which is the permission `freeStorageAndNotify` enforces. No root, no `adb root`, no developer-options switch, no per-app grant. The interesting part is what that permission does not buy. `runTrimCaches` calls `freeStorageAndNotify` with `StorageManager.FLAG_ALLOCATE_DEFY_ALL_RESERVED`, waits on the observer until it finishes, then returns zero without ever inspecting `obs.result` — the shell user is allowed to ask, and is never told the answer. A build that refused the call outright still shows up, because the exception the wrapper prints breaks the silence that otherwise means success; a build that granted the permission and freed nothing looks identical to one that freed a gigabyte. Measuring free space before and after, which is what the Android Storage Analyzer does, is the only route to an honest number.

Failure messages, decoded

Message	Meaning
Invalid suffix:	`runTrimCaches` parses the size argument itself and prints this, followed by what you typed, when the suffix is not one it knows. Nothing was trimmed. The same parser is where the multiplication happens, and it works in powers of 1024, so a suffix it accepts still may not mean what a disk vendor would mean by it.
Error: expected number at:	The argument was not a number at all — most often a swapped argument order, or a package name typed after the command out of habit from `pm clear`. Nothing ran. As with every refusal here, the tell is simply that the command printed anything whatsoever.
Exception occurred while executing 'trim-caches':	The wrapper caught a `Throwable` thrown out of `freeStorageAndNotify` and dumped a stack trace; a build that never granted `CLEAR_APP_CACHE` to the shell user is the case this covers. `classifyTrimCaches` treats every non-empty output as a refusal, which is the only safe reading when success carries no positive signal of its own.

What it changes, and the way back

It deletes cached files, not user data: no account, save file or download is touched, and every app rebuilds what it needs the next time it runs. There is nothing to restore, and no command that could — the way back is simply using the apps again. What you do see is the cost: apps start and reload more slowly while their caches refill, and the command never reports how much it freed, so measure free space before and after with `df` or `dumpsys diskstats`.

Version and vendor notes

The system decides what is disposable, not you. Which app caches get dropped, and in what order, is a platform policy this command cannot influence.
The suffix is parsed as a power of 1024, so `1G` is 1 GiB rather than 1 000 000 000 bytes.

We have a UI for this

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

Open Android Storage Analyzer

Related commands

Commands that turn up in the same session as pm trim-caches.

Command	What it does
pm clear	Wipes an app's data — or, on Android 13 and later, only its cache.
dumpsys diskstats	Free space per partition, a disk write latency check, and a cached per-app breakdown of what is using storage.
df	Reports free and used space per mounted filesystem.
du	Reports how much disk space a directory tree occupies.

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 path	Prints the absolute paths of the APK files that make up an installed package.
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 disable-user	Switches a package off for one Android user without removing it — the reversible alternative to uninstalling.
pm install	Installs one APK that is already on the device, which is what `adb install` does under the hood.
pm install-create	Opens an install session so several APKs — a base plus its splits — are installed as one atomic unit.

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.