Format:ProGuard and R8 mapping file
| Extensions | mapping.txt, .map |
|---|---|
| License | GPL-2.0 (ProGuard); R8 BSD-3-Clause |
| Website | https://github.com/Guardsquare/proguard |
| On this wiki | Facts · Code · Notes · Topics |
The mapping.txt that ProGuard, R8 and DexGuard write with -printmapping: text lines 'original -> obfuscated:' for classes and indented member lines, used by retrace and -applymapping to restore names in obfuscated Android code.
What it is
ProGuard and R8 (the Android Gradle default, also DexGuard) rename classes, methods and fields to short names like a.b.c. With -printmapping mapping.txt (Gradle writes build/outputs/mapping/<variant>/mapping.txt) they save the translation. Release APKs do not contain it; it belongs to the developer's build. If you have one for the exact build, the names can be restored; without it you work from structure (see Format:DEX).
Syntax
UTF-8 text, # comment lines (R8 puts compiler and map-id metadata there, Unverified: exact keys), no other header. From MappingPrinter.java and MappingReader.java (Guardsquare/proguard):
com.example.MyClass -> a.a:
int fieldName -> a
1:5:void doThing(java.lang.String,int) -> b
void other() -> c
- A class line ends with
:and readsoriginalExternalName -> newName:(dots, not slashes). - Field lines are indented four spaces:
type name -> newName. - Method lines: optional
startLine:endLine:(line-number range in the obfuscated code), thenreturnType name(argTypes) -> newName. Inlined methods may carry an extra:originalStart:originalEndafter the range (R8 adds more, Unverified). - The same obfuscated method name can map to several originals (overloads share
a), distinguished by signature and line range.
R8 starts the file with # lines that identify it: # compiler: R8, # compiler_version: ..., # min_api: N (DEX output), # compiler_hash: ... (development builds), # common_typos_disable, and a JSON line with id com.android.tools.r8.mapping and a map version (R8 knows 1.0, 2.0, 2.1, 2.2, 2.3; 2.2 is the stable one), plus pg_map_id/pg_map_hash lines. Source: R8 ProguardMapMarkerInfo.java and MapVersion.java; see Fact:ProGuard and R8 mapping file/identification/R8 mapping file preamble and Tool:R8. Unverified: the exact JSON line spelling and how versions 2.x change the member lines.
Applying it
- Stack traces:
retrace mapping.txt stacktrace.txt(ReTrace, ships with ProGuard; R8 has its ownretracein the Android SDK cmdline tools). Without line number tables, ambiguous methods list all candidates. - Incremental builds:
-applymapping mapping.txtmakes a new obfuscation run reuse the names. - Reverse engineering: jadx can load a mapping file (Unverified: menu File > Open mapping, option name in jadx) to show original names; scripts can also rename in Ghidra/IDA via the class lines.
- Unrelated to this:
-renamesourcefileattributereplaces the SourceFile attribute, so traces show a fixed string.
See Format:DEX, Format:APK, Platform:Android.
Code & repositories
- https://github.com/Guardsquare/proguard @
be8170263eb363bd82bbab81b874b693c6f669a6· license: GPL-2.0
ProGuard source and manual: MappingPrinter/MappingReader and ReTrace docs.
Tested on: source read, not run: source read, not run · checked 2026-10-18; last activity 2026-08-24; Note: the latest release ships binaries; the wiki links only the source, never the binaries