Apktool Documentation

A tool for reverse engineering Android apk files

25,268 stars Java Java 1 file · ~4,894 tokens #9patch#android#apk#apktool#arsc#reverse-engineering
RAW Doc

1. Project Overview & Quickstart (iBotPeaches/Apktool)

Apktool

This is the repository for Apktool. The website is at the apktool.org repository.


Apktool is a tool for reverse engineering third-party, closed, binary, Android apps. It can decode resources to nearly original form and rebuild them after making some modifications; it makes it possible to debug smali code step-by-step. It also makes working with apps easier thanks to project-like file structure and automation of some repetitive tasks such as building apk, etc.

Apktool is NOT intended for piracy and other non-legal uses. It could be used for localizing and adding features, adding support for custom platforms, and other GOOD purposes. Just try to be fair with the authors of an app, that you use and probably like.

Branches

  • main - Apktool 3.x branch
  • 2.x - Maintenance branch for Apktool 2.x releases

Support

Security Vulnerabilities

If you discover a security vulnerability within Apktool, please send an e-mail to Connor Tumbleson at connor.tumbleson(at)gmail.com. All security vulnerabilities will be promptly addressed.

Sponsors

Special thanks goes to the following sponsors:

Sourcetoad

Sourcetoad is an award-winning software and app development firm committed to the co-creation of technology solutions that solve complex business problems, delight users, and help our clients achieve their goals.

Emerge Tools

Emerge Tools is a suite of revolutionary products designed to supercharge mobile apps and the teams that build them.

2. Official Technical Reference & Guides (iBotPeaches/apktool.org)

File: README.md

Apktool Website

This is the https://apktool.org website written in Docusaurus. The tool is at the Apktool repository.

Installation

bash
npm install

Local Development

bash
npm run start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

File: docs/build.mdx

title: Build Guide sidebar_position: 1

Build Apktool

Apktool is a project that contains a collection of subprojects and dependencies.

  • brut.apktool.lib - Main Library
  • brut.apktool.cli - CLI Interface
  • brut.j.dir - Utility
  • brut.j.util - Utility
  • brut.j.common - Utility

Requirements

Build Steps

First clone the repository from GitHub

  1. Navigate to the Apktool folder and for the remaining steps use ./gradlew for Unix based systems or gradlew.bat for Windows.
  2. You can build the project in two ways:

:::info
v2.10 moved from Proguard to R8, but kept the naming to Proguard for the time being. This will be updated in the future.
:::

Without R8 (JDK > 8)

bash
[./gradlew][gradlew.bat] build shadowJar
  • Creating a jar file: brut.apktool/apktool-cli/build/libs/apktool-cli-all.jar.

With R8 (JDK > 11):

bash
[./gradlew][gradlew.bat] build shadowJar proguard
  • Creating a jar file: brut.apktool/apktool-cli/build/libs/apktool-vXXX.jar.

Windows Requirements

:::caution
Be aware of directory path length limitations on Windows.
:::

Windows has some limitations regarding max filepath. At one location in Apktool, we have a 218 character directory path
which means due to the limitation of max 255 characters on Windows we need to enforce some requirements.

This leaves 37 characters total to clone the project on Windows. For example, I can clone this project to the location

text
C:/Users/Connor/Desktop/Apktool

This is 31 characters, which allows Apktool to be cloned properly. Cloning the project into a directory longer than 37
characters will not work.

File: docs/cli-parameters.mdx

title: CLI Parameters sidebar_position: 3

Utility Options

Options used for utility commands (apktool {options})

text
h, help
  • Dumps out all usage output.
text
v, version
  • Outputs the current software version. (Ex: 1.5.2)

Decoding Options

Options used for decoding commands (apktool d file.apk {options})

text
-a, --all-src
  • Disassembles all dex files, including unknown ones.
    • Includes dex files that aren't classes*.dex located at the root.
text
-f, --force
  • Forces the deletion of the destination directory.
text
--ignore-raw-values
  • Ignore raw attribute values in XML resource files.
    • By default, raw values are respected if originally preserved.
text
-j, --jobs <NUM>
  • Sets the number of threads to use when parallel operations are available.
    • Defaults to the number of processors available, with a max of 8.
text
--keep-broken-res
  • Use if an error was thrown and some resources were dropped and you want to decode them anyway.
    • E.g. Invalid config flags detected. Dropping resources.
    • You will have to fix them manually before building.
text
-l, --lib :<location>
  • Use to specify a dynamic library location.
    • E.g. --lib com.google.android.test.shared_library:/tmp/shared_library.apk
    • This can be called multiple times to add multiple libraries.
text
--match-original
  • Matches the generated files as close as possible to the originals.
    • Comes at the cost of possibly preventing re-build.
text
--no-assets
  • Prevents decoding/copying unknown asset files.
text
--no-debug-info
  • Prevents baksmali from writing out debug info. (.local, .param, .line, etc.).
text
-o, --output <DIR>
  • Sets the name of the output directory.
    • The Default is apk.out.
text
--only-manifest
  • Only decode AndroidManifest.xml without resources.
text
-p, --frame-path <DIR>
  • Sets the folder framework files are stored/read from.
text
-r, --no-res
  • Prevents decompiling resources.
    • Keeps resources.arsc intact.
text
--res-resolve-mode <mode>
  • Sets the mode used when resolving resources.
    • default - Adds dummy entries only for referenced resources that cannot be resolved.
    • greedy - Adds dummy entries for all missing resources in the resource table, including unreferenced resources.
    • lazy - Ignores missing resources, including referenced resources that cannot be resolved.
text
-s, --no-src
  • Prevents disassembling dex files.
    • Leaves the dex files untouched and moves them upon build.
text
-t, --frame-tag <TAG>
  • Uses framework files tagged by TAG.

Building Options

Options used for building commands (apktool b folder {options})

text
--aapt <FILE>
  • Loads aapt2 binaries from the specified location.
    • These are used instead of the internal version.
text
--copy-original
  • Copies the original AndroidManifest.xml and META-INF.
text
--debuggable
  • Adds debuggable="true" to AndroidManifest.xml.
text
-f, --force
  • Overwrites existing files during build.
    • Includes resources and sources.
text
-j, --jobs <NUM>
  • Sets the number of threads to use when parallel operations are available.
    • Defaults to the number of processors available, with a max of 8.
text
-l, --lib :<location>
  • Use to specify a dynamic library location.
    • E.g. --lib com.google.android.test.shared_library:/tmp/shared_library.apk
    • This can be called multiple times to add multiple libraries.
text
--net-sec-conf
  • Adds a generic Network Security Configuration file in the apk.
text
--no-apk
  • Disables repacking of the built files into a new apk.
text
--no-crunch
  • Disables crunching resource files during build.
    • This prevents automatic bitmap optimization by aapt/aapt2.
text
-o, --output <FILE>
  • Sets the name of the output apk.
    • The Default is dist/{apkname}.apk.
text
-p, --frame-path <DIR>
  • Sets the folder framework files are stored/read from.

Install Framework Options

Options used for install-framework commands (apktool if|install-framework {options})

text
-p, --frame-path <DIR>
  • Sets the folder framework files are stored/read from.
text
-t, --frame-tag <TAG>
  • Suffixes framework files with TAG.

Clean Frameworks Options

  • Cleans untagged framework files by default.

Options used for clean-frameworks commands (apktool cf|clean-frameworks {options})

text
-a, --all
  • Cleans all framework files regardless of their tag.
text
-p, --frame-path <DIR>
  • Sets the folder framework files are read from.
text
-t, --frame-tag <TAG>
  • Cleans framework files with the specified tag.

List Framework Directory Options

  • Lists untagged framework files by default.

Options used for list-frameworks commands (apktool lf|list-frameworks {options})

text
-a, --all
  • Lists all framework files regardless of their tag.
text
-p, --frame-path <DIR>
  • Sets the folder framework files are read from.
text
-t, --frame-tag <TAG>
  • Lists framework files with the specified tag.

Common Options

Options that can be used with any command

text
-q, --quiet
  • Quiet output.
text
-v, --verbose
  • Verbose output.
    • Includes any log messages tagged with FINE.

File: docs/faq.mdx

title: FAQ sidebar_position: 4

Is it possible to run Apktool on an Android device?

Sadly not officially, there are some incompatibilities with running the aapt binary on Android.
Additionally, older builds of Android have problems with using the java.nio library. Unofficial
packages have only succeeded with cross-compiling binaries.

Where can I download the source of Apktool?

From either the GitHub or Bitbucket repositories.

The resulting APK is much smaller than the original. Is something wrong?

There are a few reasons this might occur.

  • Apktool builds unsigned APKs. This means some directories and files like META-INF are missing.
  • Updated build process - Apktool uses modern versions of aapt/aapt2 which may reduce file sizes.

There is no `META-INF` directory in the resulting APK. Is this ok?

Yes, META-INF contains the APK's signatures. After modifying an APK it is no longer signed. You
can use -c / --copy-original to retain these signatures. However, -c will use the original
AndroidManifest.xml and is only capable of working with the original APK signature v1 scheme.

What are "Magic APKs"?

There are some APKs that are built with modified build tools intended for specific OEMs. These APKs
are not built with regular AOSP tools and are not compatible with Apktool. Apktool will not be
able to decode or build these APKs.

Could I integrate Apktool into my own project? Could I modify it? Do I have to credit you?

The Apache license, which Apktool uses, answers all these questions.

  • Yes, you can redistribute and/or modify Apktool without permission.
  • However, it would be nice to add contributors (brut.all, iBotPeaches, JesusFreke) to your credits.

Where does Apktool store framework files?

  • Windows: $HOME/AppData/Local/apktool
  • Mac: $HOME/Library/apktool
  • Linux: $HOME/.local/share/apktool

File: docs/install.mdx

Install Guide

:::info
A minimum of Java 8 is required to run Apktool.
:::

Windows

:::info
As Windows is case-insensitive please adjust case sensitivity for correct operation.
:::

  1. Download the Windows wrapper script. (Right click, Save Link As apktool.bat)
  2. Download the latest version of Apktool.
  3. Rename downloaded jar to apktool.jar.
  4. Move both apktool.jar and apktool.bat to your Windows directory. (Usually C://Windows)
  5. If you do not have access to C://Windows, you can place the two files anywhere and add that directory to your Environment Variables System PATH variable.
  6. Try running apktool via the command prompt.

Linux

  1. Download the Linux wrapper script. (Right click, Save Link As apktool)
  2. Download the latest version of Apktool.
  3. Rename the downloaded jar to apktool.jar.
  4. Move both apktool.jar and apktool to /usr/local/bin. (root needed)
  5. Make sure both files are executable. (chmod +x)
  6. Try running apktool via CLI.

Mac

  1. Download the Mac wrapper script. (Right click, Save Link As apktool)
  2. Download the latest version of Apktool.
  3. Rename the downloaded jar to apktool.jar.
  4. Move both apktool.jar and apktool to /usr/local/bin. (root needed)
  5. Make sure both files are executable. (chmod +x)
  6. Try running apktool via CLI.

Brew

  1. Install Homebrew as described in this page.
  2. Execute the command brew install apktool in the terminal.
  3. Try running apktool via CLI.

:::tip
Wrapper scripts are not needed but they are helpful, so you don't have to type java -jar apktool.jar repeatedly.
:::

File: docs/unreleased.mdx

title: Upcoming Release

:::info

The changelog of the upcoming release, subject to change prior to finalization.

:::

  • [#4175] Move required build version to JDK 17.
  • [#4155] Move to Gradle 9.
  • [#4201] Support decoding to an empty folder. (Thanks IgorEisberg & iTrooz)
  • [#4177] Improve performance and handling of UTF-8 in apktool.yml. (Thanks IgorEisberg)
  • [#4205] Upgrade xmlunit-legacy to 2.13.0.
  • [#4206] Upgrade gradle/actions to 6.3.0.
  • [#4207] Upgrade gradle to 9.7.0.

File: wiki/the-basics/building.mdx

title: Building sidebar_position: 3

The build option can be invoked either from b or build like shown below

bash
$ apktool b foo.jar.out
# builds foo.jar.out folder into foo.jar.out/dist/foo.jar

$ apktool build foo.jar.out
# builds foo.jar.out folder into foo.jar.out/dist/foo.jar

$ apktool b bar
# builds bar folder into bar/dist/bar.apk

$ apktool b .
# builds current directory into ./dist

$ apktool b bar -o new_bar.apk
# builds bar folder into new_bar.apk

$ apktool b bar.apk
# WRONG: brut.androlib.AndrolibException: brut.directory.PathNotExist: apktool.yml
# Must use folder, not apk/jar file

:::info
In order to run a rebuilt application, you must resign it.
Android documentation can help with this.
:::

File: wiki/the-basics/decoding.mdx

title: Decoding sidebar_position: 2

The decode option can be invoked either from d or decode like shown below.

bash
$ apktool d foo.jar
# decodes foo.jar to foo.jar.out folder

$ apktool decode foo.jar
# decodes foo.jar to foo.jar.out folder

$ apktool d bar.apk
# decodes bar.apk to bar folder

$ apktool decode bar.apk
# decodes bar.apk to bar folder

$ apktool d bar.apk -o baz
# decodes bar.apk to baz folder

File: wiki/the-basics/frameworks.mdx

title: Frameworks sidebar_position: 4

Frameworks can be installed either from if or install-framework, additionally with two paramaters.

  • -p, --frame-path <directory> - Store framework files into the <dir>.
  • -t, --tag <tag> - Tag frameworks using <dir> as the tag.

This allows for finer control over how the files are stored and named.

bash
$ apktool if framework-res.apk
I: Framework installed to: 1.apk
# pkgId of framework-res.apk determines the number. (which is 0x01)

$ apktool if com.htc.resources.apk
I: Framework installed to: 2.apk
# pkgId of com.htc.resources is 0x02

$ apktool if com.htc.resources.apk -t htc
I: Framework installed to: 2-htc.apk
# pkgId-tag.apk

$ apktool if framework-res.apk -p foo/bar
I: Framework installed to: foo/bar/1.apk

$ apktool if framework-res.apk -t baz -p foo/bar
I: Framework installed to: foo/bar/1-baz.apk

File: wiki/the-basics/intro.mdx

title: Introduction sidebar_position: 1

First lets take a lesson into apk files. Apks are nothing more than a zip file containing resources and assembled java code.
If you were to simply unzip an apk like so, you would be left with files such as classes.dex and resources.arsc.

shell
$ unzip testapp.apk
Archive:  testapp.apk
inflating: AndroidManifest.xml
inflating: classes.dex
extracting: res/drawable-hdpi/ic_launcher.png
inflating: res/xml/literals.xml
inflating: res/xml/references.xml
extracting: resources.arsc

However, at this point you have simply inflated compiled sources. If you tried to view AndroidManifest.xml. You'd be left viewing a malformed file.

Obviously, editing or viewing a compiled file is next to impossible. That is where Apktool comes into play.

shell
$ apktool d testapp.apk
I: Using Apktool 2.0.0 on testapp.apk
I: Loading resource table...
I: Decoding AndroidManifest.xml with resources...
I: Loading resource table from file: 1.apk
I: Regular manifest package...
I: Decoding file-resources...
I: Decoding values */* XMLs...
I: Baksmaling classes.dex...
I: Copying assets and libs...

Viewing AndroidManifest.xml again results in something much more human readable

xml
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest xmlns:android="https://schemas.android.com/apk/res/android" package="brut.apktool.testapp"
          platformBuildVersionCode="21" platformBuildVersionName="APKTOOL" />

In addition to XMLs, resources such as 9 patch images, layouts, strings, and much more are correctly decoded to source form.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#9patch Browse 9patch catalog → #android Browse android catalog → #apk Browse apk catalog → #apktool Browse apktool catalog → #arsc Browse arsc catalog → #reverse-engineering Browse reverse-engineering catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →