Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:ProGuard and R8 mapping file

From ReverseEngineering.wiki
Format
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 reads originalExternalName -> 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), then returnType name(argTypes) -> newName. Inlined methods may carry an extra :originalStart:originalEnd after 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 own retrace in the Android SDK cmdline tools). Without line number tables, ambiguous methods list all candidates.
  • Incremental builds: -applymapping mapping.txt makes 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: -renamesourcefileattribute replaces 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