# Apktool: Decode, Modify, and Rebuild Android APK Files

> Apktool is an open source Java tool for reverse engineering Android APK files. It decodes resources to nearly original form, rebuilds APKs after modifications, and supports step-by-step debugging of smali code. The current branch is 3.x, with v3.0.3 released on 2026-07-20.

**iBotPeaches/Apktool** — A tool for reverse engineering Android apk files

- Repository: https://github.com/iBotPeaches/Apktool
- Website: https://apktool.org
- Stars: 25,685 · Forks: 4,018
- Language: Java
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ibotpeaches-apktool

## What Apktool Does and Its Intended Use Cases

Android APK files are zip archives containing compiled Java bytecode, compiled XML resources, drawable assets, native libraries, and a manifest. Without tooling, the resources are unreadable as compiled binary XML, and the code is Dalvik bytecode rather than human-readable source. Apktool reverses this transformation for the resources: it decodes compiled XML layouts, manifests, and string tables back into readable form, and it converts code to smali, an assembly-like representation of Dalvik bytecode.

The README states that Apktool is "NOT intended for piracy and other non-legal uses" and lists the legitimate purposes explicitly: localizing an app, adding features, adding support for custom platforms, and other legitimate engineering purposes. It emphasizes being "fair with the authors of an app."

Practical use cases that fall within the stated scope include: checking how an app handles localization strings before contributing a translation, inspecting a compiled app's resource structure for compatibility work, debugging your own app's compiled output to verify that a build process works as intended, and security research on apps you own or have permission to analyze.

The 3.x branch is the current development line. A 2.x maintenance branch continues to receive updates for teams on older workflows. The last push to the main branch was on 2026-09-28 and v3.0.3 was released on 2026-07-20.

## Decoding APK Resources to Editable Form

When Apktool decodes an APK, it produces a project directory that mirrors the app's structure in a readable form. XML resources are decoded from their compiled binary format back into readable XML. Drawable assets are extracted. The AndroidManifest.xml, which is compiled into a binary format inside APKs, is decoded into its original plain text XML form.

This project-like file structure is one of the features the README highlights: it makes it possible to navigate the app's resources with standard text editors and version control tools, rather than writing custom binary parsing code for each resource type.

Modifications made to the decoded project directory (editing a string resource, replacing an icon, changing a manifest attribute) can then be rebuilt into a new APK. Apktool reassembles the project, recompiles the XML resources into their binary form, and packages everything back into an APK. The rebuilt APK will need to be signed before it can be installed on an Android device.

The README describes this cycle as the core workflow: decode, modify, rebuild. The tool also automates "some repetitive tasks such as building apk," meaning it handles the compilation steps that would otherwise require manual invocation of Android build tooling.

## Smali and Step-by-Step Code Debugging

Dalvik bytecode, the format in which Android apps run, does not directly map to readable Java source code. Apktool converts this bytecode to smali, a human-readable assembly-like representation. Smali files use a syntax that mirrors the structure of Dalvik instructions: method definitions, registers, class references, and opcodes are all expressed in a textual form.

The README states that Apktool makes it possible to debug smali code step-by-step. This is a significant capability for anyone working at a low level with Android app internals: it allows setting breakpoints and stepping through execution in the smali representation rather than requiring a full Java source-level decompilation.

This smali output is not a high-level Java reconstruction. Engineers reading smali need to understand Dalvik register semantics and opcode conventions. For reading high-level Java logic from an app, a decompiler like jadx is the appropriate tool. Apktool's smali output is the right level of abstraction for engineers who need to understand precisely what a specific method does at the bytecode level or who are working with obfuscated code where high-level decompilation produces confusing results.

The `brut.apktool/` subdirectory in the repository contains the main Apktool implementation. Supporting libraries are organized as separate subprojects: `brut.j.util/`, `brut.j.common/`, `brut.j.dir/`, `brut.j.xml/`, and `brut.j.yaml/` each handle a specific responsibility in the APK processing pipeline.

## Installing Apktool and the Jar Distribution

Apktool is distributed as a runnable Java JAR file rather than through a system package manager. The README links to the downloads page at Bitbucket (`https://bitbucket.org/iBotPeaches/apktool/downloads`) and a mirror at `https://connortumbleson.com/apktool`. Installation instructions for Windows, Linux, and macOS are documented at apktool.org.

The README provides no inline installation commands, directing users to the documentation site at apktool.org/wiki/the-basics/intro for a complete getting-started walkthrough. This is the reference point for command syntax, flags, and platform-specific wrapper script setup.

For users building Apktool from source, the repository uses Gradle with a wrapper script. The build documentation is at apktool.org/docs/build. The project structure follows a multi-module Gradle layout with `settings.gradle.kts` and `build.gradle.kts` at the root, and individual submodule directories for the main tool and its supporting libraries.

Apktool requires Java to run, matching the tool's Java implementation. The specific Java version requirement is not stated in the README; the build documentation at apktool.org is the authoritative source.

## Legal Status and the Non-Piracy Disclaimer

The README is explicit about the legal framing. The opening section states: "Apktool is NOT intended for piracy and other non-legal uses." This is unusual for a technical tool README and reflects the reality that reverse engineering tooling occupies a legally contested area in many jurisdictions.

The legitimate uses the README names are app localization, adding features, adding support for custom platforms, and security research. These align with uses that are generally recognized as lawful in jurisdictions that permit reverse engineering for interoperability, security analysis, and educational purposes.

The legal status of reverse engineering APKs varies by country and by the terms of service of the specific application. The README does not provide legal advice and instead frames the issue as a matter of fairness toward app authors. Engineers using Apktool in professional contexts should verify that their specific use case is permitted under applicable laws and the target app's terms of service.

The tool is licensed under Apache-2.0, which places no restrictions on how the compiled JAR may be used. The license covers the tool itself, not the apps that Apktool is applied to.

## Repository Structure and the 3.x Branch

The repository separates Apktool's functionality across several Gradle subprojects. The `brut.apktool/` directory contains the main Apktool CLI and core logic. The `brut.j.util/`, `brut.j.common/`, `brut.j.dir/`, `brut.j.xml/`, and `brut.j.yaml/` directories are supporting utility libraries. This modular layout means different components of APK parsing (XML handling, directory traversal, YAML configuration) are maintained independently.

The main branch tracks the 3.x line. The `2.x` branch is a maintenance branch that continues to receive fixes for users on older Apktool versions. The README documents both branches and their purpose.

A `ROADMAP.md` file in the repository root indicates that the project maintains a published roadmap, which is less common in single-author open source projects. The changelog and release information are available through the project blog at apktool.org/blog rather than a CHANGELOG file in the repository. Security vulnerabilities should be reported to the maintainer by email, with the contact address listed in the README.

The project also maintains a presence on Bitbucket as a source mirror alongside the primary GitHub repository.

## Apktool vs jadx: Resource Decoding vs Code Decompilation

jadx is an open source decompiler that converts Android Dalvik bytecode into Java (and optionally Kotlin) source code. Its primary output is human-readable Java class files, making it the right tool when the goal is to understand the Java business logic inside an app: reading API calls, tracing authentication flows, or understanding how data is processed.

Apktool's primary output is different. It decodes APK resources (XML layouts, manifests, string tables, drawables) into editable files, and it converts bytecode to smali assembly rather than Java source. The rebuild workflow (decode, modify, repack) is Apktool's defining feature and has no direct equivalent in jadx, which is read-only.

The two tools are often used together. A security researcher might use Apktool to decode an APK and inspect its manifest and resources, then use jadx to read the Java logic of specific classes. They address different aspects of the same APK: Apktool for structure and resources, jadx for decompiled logic.

For teams working with heavily obfuscated apps, Apktool's smali output is sometimes more useful than jadx's Java output because obfuscation that defeats Java decompilation still produces valid smali. Engineers who understand Dalvik opcodes can reason about smali even when Java decompilation produces unreadable results.

## Conclusion

Apktool is the standard tool for engineers who need to decode, inspect, and rebuild Android APK resources for legitimate purposes: localization, security research, CTF challenges, and custom platform support. It is not the right tool for reading Java business logic from an app, which is jadx's domain. Before using Apktool on any application, confirm that your use case is permitted under the app's terms of service and the laws that apply in your jurisdiction. Downloads and installation instructions are at apktool.org.

## FAQ

### How do I use Apktool to decompile an APK?

Apktool decodes an APK by running the decode command against the APK file, which produces a project directory containing editable XML resources, smali bytecode files, and extracted assets. The full command syntax is documented at apktool.org/wiki/the-basics/intro. The JAR is available for download at the Bitbucket downloads page linked in the README.

### Is Apktool safe to use?

Apktool is an open source Java tool with Apache-2.0 licensing and an active maintenance history. It decodes and rebuilds APK files locally. The README does not document any network activity or data collection in the tool itself. Whether using Apktool on a specific app is legally and ethically appropriate depends on the app's terms of service and applicable law.

### Is using Apktool legal?

The README states that Apktool is not intended for piracy or non-legal uses and explicitly names legitimate uses: localization, adding features, and custom platform support. The legality of reverse engineering an app depends on the laws of your jurisdiction and the specific app's terms of service. Apktool itself is Apache-2.0 licensed; how it is applied is the user's responsibility.

### How do I install Apktool on Windows?

Apktool is distributed as a runnable JAR. Download it from the Bitbucket downloads page linked in the README or the mirror at connortumbleson.com/apktool, then follow the Windows installation steps at apktool.org. The README does not include inline installation commands.

## Sources

- [iBotPeaches/Apktool on GitHub](https://github.com/iBotPeaches/Apktool)
- [License: Apache-2.0](https://github.com/iBotPeaches/Apktool/blob/main/LICENSE)
- [Project website](https://apktool.org)
- [README](https://github.com/iBotPeaches/Apktool/blob/main/README.md)
- [Releases](https://github.com/iBotPeaches/Apktool/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ibotpeaches-apktool