APKTool Guide: Decompile, Recompile & Sign APKs (2026)

Part of the modding hub: How to Mod an APK · Phone alternative: MT Manager guide · Source file: Extract an APK.

APKTool is the command-line standard for decoding an APK into editable Smali and resources, rebuilding it, and handing the output to apksigner for signing. It runs on Windows, Mac, and Linux, needs only Java, and is the tool of record for deep edits, system apps, and scripted builds.

Everything below is one workflow: install, decode, understand the folder layout, edit, rebuild, sign, and fix the four errors that cause most failed builds. Where the phone tools are faster, this guide says so and points at them instead.

What Is APKTool?

APKTool decodes an APK into a folder of Smali files, resource tables, a decoded manifest, and apktool.yml, then rebuilds that folder into a installable package. Unlike decompilers aimed at reading, APKTool is built to round-trip: decode, change, rebuild, repeat.

APKTool vs MT Manager

MT Manager wins for one edit on a phone, no setup, no cable. APKTool wins when you need to search across many files, keep a pristine copy under version control, handle system frameworks, or script the same change across builds. Use both: MT Manager to explore, APKTool to work.

How to Install APKTool

Installation is a jar file plus Java. Nothing compiles, nothing installs system-wide, and the same steps work on all three desktop platforms.

Windows

Install a Java 11 or newer runtime, download apktool.jar from the official GitHub releases page, and drop a wrapper .bat next to it containing java -jar apktool.jar %*. Rename the wrapper to apktool.bat and put both on your PATH.

Mac and Linux

Install Java from your package manager, download the jar, and create a wrapper script named apktool with java -jar /path/to/apktool.jar "$@", then chmod +x it. Put it somewhere on your PATH and confirm with apktool --version.

Java Requirement

Java 11 or newer. Check with java -version before anything else: a missing or ancient runtime is the single most common install failure, and it presents as a confusing class-version error rather than a clear message.

APKTool Basic Commands

Four commands cover daily use. Learn these before anything else and you can complete most jobs.

apktool d (Decode)

apktool d app.apk -o app-folder decodes into a named folder. Add -s to keep the original classes.dex un-decoded when you only need resources, which is much faster on large apps.

apktool b (Build)

apktool b app-folder rebuilds and writes app-folder/dist/app.apk. The build reads apktool.yml for packaging settings, so the output behaves like the original archive rather than a generic rezip.

apktool if (Install Framework)

apktool if framework.apk installs a framework file, required before decoding system apps that reference vendor frameworks. Without it, decoding a system package fails with a missing-framework error immediately.

apktool empty-framework-dir

Clears cached framework files when a decode starts failing after an APKTool update. Run it once when errors mention framework IDs you never installed.

How to Decompile With APKTool

Run apktool d app.apk, then look at what came out. Reading the structure before editing saves the most time of any habit in this guide.

Useful Decode Flags

-o name names the output folder, -s keeps classes.dex as-is when you only need resources, and -f overwrites an existing folder without prompting. Resource-only decodes with -s finish several times faster on large packages, which matters when you are iterating.

Folder Structure

smali/ holds the decompiled code, one folder per DEX when the package is multidex. res/ holds decoded resources, AndroidManifest.xml sits at the top level, and apktool.yml records the packaging metadata. original/ keeps untouched pieces of the archive.

Read the Manifest

Permissions, activities, services, and SDK versions are all in plain XML here. This is the fastest way to understand what an app does before deciding whether to touch it at all.

Read Smali

Smali is the readable assembly form of Dalvik bytecode. Method bodies show as instruction lists, string constants show as const-string lines, and conditions show as conditional jumps. Search for visible strings first: they anchor you to the right method quickly.

A Reference Decode Session

apktool d app.apk -o app-decode
cd app-decode
grep -rn "Remove Ads" res/values/strings.xml
grep -rn "isPremium" smali*/ | head -20

Two greps answer the two questions people open a decode for: where the visible text lives, and where the flag behind it is checked. On a 60 MB game this whole inspection takes under a minute once the decode finishes.

How to Edit With APKTool

Edit one thing per cycle. Save, rebuild, and test before touching anything else, because a crash with three edits tells you nothing about which one caused it.

Edit AndroidManifest.xml

Change permissions, the launcher activity, or the app label directly in XML. Keep the file well-formed: a stray tag fails at build time with an error naming the line, which is cheaper to catch than a runtime crash.

Edit Smali Code

Change a comparison, flip a return value, or skip a branch. Keep register counts intact: adding a register to a method means fixing every instruction in it, which is exactly the kind of change that looks right and crashes in practice.

Two edits are almost always safe: changing a const/4 immediate value, and replacing one conditional jump with its opposite. Both keep the method’s register shape untouched.

Edit Resources

res/values/strings.xml holds decoded strings, and res/values/ holds numbers and colors. This is the safest edit category: wrong values look wrong, they rarely crash the app.

Keep the Pristine Decode

Copy the decode folder before your first edit. When a rebuild crashes, diff -r pristine edited prints exactly what changed, and that diff is faster to review than your memory of what you touched twenty minutes ago.

How to Recompile With APKTool

apktool b app-folder produces the rebuilt package. Watch the output: success prints the path to dist/, failure names the file that broke.

Useful Build Flags

-o path writes the output somewhere specific, and -f overwrites without prompting. Build failures print the first offending file only, so fix, rebuild, and repeat rather than trying to reason about a list that stops at error one.

Common Build Errors

A Smali syntax error names the file and line. A resource conflict names the duplicate entry. A missing file means your edit deleted something the manifest still references. Fix the named file, rebuild, and never sign a failed build.

The recompile guide walks each error in detail with the exact messages to match.

How to Sign APKTool Output

APKTool does not sign, deliberately. Feed the output to apksigner: apksigner sign --ks my.keystore app-folder/dist/app.apk, then verify with apksigner verify --print-certs. Full keystore setup, scheme selection, and error handling live in the sign-an-APK guide.

One habit worth building: sign and verify in the same breath. apksigner verify right after signing catches a keystore that silently did not apply, which otherwise shows up as an install failure two steps later with a less helpful message.

Using APKTool With Frameworks

System apps pull resources from shared framework files that are not inside the package. Install them with apktool if before decoding, or the decode fails before it reads a single resource. Vendor ROMs sometimes need their own framework dumps, extracted from the device and installed the same way.

Framework files accumulate across projects and occasionally go stale after an APKTool upgrade. apktool empty-framework-dir clears them, and it is the first thing to try when decode errors start mentioning framework IDs you never deliberately installed.

A Full Round Trip

The complete cycle in eight lines, from installed app to verified mod:

adb shell pm path com.example.app
adb pull /data/app/.../base.apk original.apk
apktool d original.apk -o work
# ...edit one file inside work/...
apktool b work
apksigner sign --ks my.keystore work/dist/original.apk
apksigner verify --print-certs work/dist/original.apk
adb uninstall com.example.app
adb install work/dist/original.apk

Timing on a mid-size app: the decode takes 20 to 60 seconds, the edit takes as long as the search does, and the rebuild runs in about 10. The install step is where the original app disappears, which is why every prior step runs against copies.

Common APKTool Errors

Four errors cover most failed sessions. Each message points at its own fix.

Java Not Found or Wrong Version

The wrapper cannot reach a Java 11+ runtime. Install one, confirm with java -version, and keep the wrapper’s java call pointing at the right installation if you have several.

Framework Missing

Decoding a system package without its framework installed. Run apktool if framework.apk, or let APKTool fetch the framework from a connected device, then decode again.

Build Fails on Smali

Syntax error in an edited file. The error names the file and line: open it, compare against your pristine decode, and fix the instruction you changed. Undecoded binaries passed through your editor intact are the other common cause.

Resource ID Conflicts

Two values claim the same ID, usually after merging resource files from different builds. Remove the duplicate, or rebuild from a fresh decode and reapply your edits one at a time.

APKTool vs Other Tools

APKTool pairs naturally with JADX, covered in the decompile guide, for reading and MT Manager for quick checks on the device.

Picking Between Them in Practice

Start where you are: on a phone with a single value to change, MT Manager finishes first. On a computer with a manifest or string change, APK Editor’s forms are quicker than Smali. When the change spans files, needs a diff, or has to repeat across builds, APKTool is the only one of the three that scales.

Command Reference

The full set you will actually type, grouped by phase:

# decode
apktool d app.apk -o work          # decode into ./work
apktool d app.apk -s -o res-only   # resources only, faster
apktool if framework.apk           # install a framework first

# build
apktool b work                     # build to work/dist/
apktool b work -o out/app.apk      # build to a chosen path

# maintenance
apktool empty-framework-dir        # clear stale frameworks
apktool --version                  # confirm what is installed

Keep this block in your shell history or a scratch file. Nearly every session with the tool uses three of these seven lines.

How APKTool Fits the Wider Workflow

APKTool sits in the middle of a chain: extraction gets the file, APKTool takes it apart and puts it back together, signing makes it installable, and the install guide handles putting it on a device. Each step has its own guide, and skipping any of them produces a specific, recognizable failure.

Pull the source file with the extraction guide, decode it with the commands above, then hand the rebuilt output to the signing step when the build comes back clean.

Decode your first package with apktool d, open the manifest, and read it before changing anything. When you are ready to rebuild, the recompile and signing guides pick up exactly where this one stops.