ProGuard Usage

ProGuard index DexGuard GuardSquare Sourceforge

Usage
To run ProGuard, just type:
java -jar proguard.jar options ...
You can find the ProGuard jar in the libdirectory of the ProGuard distribution. Alternatively, the bindirectory
contains some short Linux and Windows scripts containing this command. Typically, you'll put most options in a
configuration file (say, myconfig.pro), and just call:
java -jar proguard.jar @myconfig.pro
You can combine command line options and options from configuration files. For instance:
java -jar proguard.jar @myconfig.pro -verbose
You can add comments in a configuration file, starting with a #character and continuing until the end of the
line.
Extra whitespace between words and delimiters is ignored. File names with spaces or special characters should
be quoted with single or double quotes.
Options can be grouped arbitrarily in arguments on the command line and in lines in configuration files. This
means that you can quote arbitrary sections of command line options, to avoid shell expansion of special
characters, for instance.
The order of the options is generally irrelevant. For quick experiments, you can abbreviate them to their first
unique characters.
The sections below provide more details:
Sun's JDK 1.2.2 javaccompiler produces an exception when compiling with such a library (cfr. Bug
#4216736). You probably shouldn't use this option for processing libraries.
Sun's JRE 1.4 and later fail to serialize objects with overloaded primitive fields.
Sun's JRE 1.5 pack200tool reportedly has problems with overloaded class members.
The class java.lang.reflect.Proxycan't handle overloaded methods.
Google's Dalvik VM can't handle overloaded static fields.
-useuniqueclassmembernames
Specifies to assign the same obfuscated names to class members that have the same names, and different
obfuscated names to class members that have different names (for each given class member signature).
Without the option, more class members can be mapped to the same short names like 'a', 'b', etc. The option

therefore increases the size of the resulting code slightly, but it ensures that the saved obfuscation name
mapping can always be respected in subsequent incremental obfuscation steps.
For instance, consider two distinct interfaces containing methods with the same name and signature. Without
this option, these methods may get different obfuscated names in a first obfuscation step. If a patch is then
added containing a class that implements both interfaces, ProGuard will have to enforce the same method
name for both methods in an incremental obfuscation step. The original obfuscated code is changed, in order to
keep the resulting code consistent. With this option in the initial obfuscation step, such renaming will never be
necessary.
This option is only applicable when obfuscating. In fact, if you are planning on performing incremental
obfuscation, you probably want to avoid shrinking and optimization altogether, since these steps could remove
or modify parts of your code that are essential for later additions.
-dontusemixedcaseclassnames
Specifies not to generate mixed-case class names while obfuscating. By default, obfuscated class names can
contain a mix of upper-case characters and lower-case characters. This creates perfectly acceptable and usable
jars. Only if a jar is unpacked on a platform with a case-insensitive filing system (say, Windows), the unpacking
tool may let similarly named class files overwrite each other. Code that self-destructs when it's unpacked!
Developers who really want to unpack their jars on Windows can use this option to switch off this behavior.
Obfuscated jars will become slightly larger as a result. Only applicable when obfuscating.
-keeppackagenames[package_filter]
Specifies not to obfuscate the given package names. The optional filter is a comma-separated list of package
names. Package names can contain ?, *, and ** wildcards, and they can be preceded by the ! negator. Only
applicable when obfuscating.
-flattenpackagehierarchy[package_name]
Specifies to repackage all packages that are renamed, by moving them into the single given parent package.
Without argument or with an empty string (''), the packages are moved into the root package. This option is one
example of further obfuscating package names. It can make the processed code smaller and less
comprehensible. Only applicable when obfuscating.
-repackageclasses[package_name]
Specifies to repackage all class files that are renamed, by moving them into the single given package. Without
argument or with an empty string (''), the package is removed completely. This option overrides the flattenpackagehierarchyoption. It is another example of further obfuscating package names. It can make
the processed code even smaller and less comprehensible. Its deprecated name is -defaultpackage. Only
applicable when obfuscating.

Counter-indication: classes that look for resource files in their package directories will no longer work properly if
they are moved elsewhere. When in doubt, just leave the packaging untouched by not using this option.
-keepattributes[attribute_filter]

Specifies any optional attributes to be preserved. The attributes can be specified with one or more keepattributesdirectives. The optional filter is a comma-separated list of attribute names that Java virtual
machines and ProGuard support. Attribute names can contain ?, *, and ** wildcards, and they can be preceded
by the ! negator. For example, you should at least keep the Exceptions, InnerClasses, and Signature
attributes when processing a library. You should also keep the SourceFileand LineNumberTableattributes
for producing useful obfuscated stack traces. Finally, you may want to keep annotations if your code depends on
them. Only applicable when obfuscating.
-keepparameternames
Specifies to keep the parameter names and types of methods that are kept. This option actually keeps trimmed
versions of the debugging attributes LocalVariableTableand LocalVariableTypeTable. It can be
useful when processing a library. Some IDEs can use the information to assist developers who use the library,
for example with tool tips or autocompletion. Only applicable when obfuscating.
-renamesourcefileattribute[string]
Specifies a constant string to be put in the SourceFileattributes (and SourceDirattributes) of the class
files. Note that the attribute has to be present to start with, so it also has to be preserved explicitly using the keepattributesdirective. For example, you may want to have your processed libraries and applications
produce useful obfuscated stack traces. Only applicable when obfuscating.
-adaptclassstrings[class_filter]
Specifies that string constants that correspond to class names should be obfuscated as well. Without a filter, all
string constants that correspond to class names are adapted. With a filter, only string constants in classes that
match the filter are adapted. For example, if your code contains a large number of hard-coded strings that refer
to classes, and you prefer not to keep their names, you may want to use this option. Primarily applicable when
obfuscating, although corresponding classes are automatically kept in the shrinking step too.
-adaptresourcefilenames[file_filter]
Specifies the resource files to be renamed, based on the obfuscated names of the corresponding class files (if
any). Without a filter, all resource files that correspond to class files are renamed. With a filter, only matching
files are renamed. For example, see processing resource files. Only applicable when obfuscating.
-adaptresourcefilecontents[file_filter]
Specifies the resource files whose contents are to be updated. Any class names mentioned in the resource files
are renamed, based on the obfuscated names of the corresponding classes (if any). Without a filter, the contents
of all resource files updated. With a filter, only matching files are updated. The resource files are parsed and
written using the platform's default character set. You can change this default character set by setting the
environment variable LANGor the Java system property file.encoding. For an example, see processing
resource files. Only applicable when obfuscating.

Caveat: You probably only want to apply this option to text files, since parsing and adapting binary files as text
files can cause unexpected problems. Therefore, make sure that you specify a sufficiently narrow filter.
Preverification Options-dontpreverify

Specifies not to preverify the processed class files. By default, class files are preverified if they are targeted at
Java Micro Edition or at Java 6 or higher. For Java Micro Edition, preverification is required, so you will need to
run an external preverifier on the processed code if you specify this option. For Java 6, preverification is
optional, but as of Java 7, it is required. Only when eventually targeting Android, it is not necessary, so you can
then switch it off to reduce the processing time a bit.
-microedition
Specifies that the processed class files are targeted at Java Micro Edition. The preverifier will then add the
appropriate StackMap attributes, which are different from the default StackMapTable attributes for Java
Standard Edition. For example, you will need this option if you are processing midlets.
General Options-verbose
Specifies to write out some more information during processing. If the program terminates with an exception,
this option will print out the entire stack trace, instead of just the exception message.
-dontnote[class_filter]
Specifies not to print notes about potential mistakes or omissions in the configuration, such as typos in class
names or missing options that might be useful. The optional filter is a regular expression; ProGuard doesn't
print notes about classes with matching names.
-dontwarn[class_filter]
Specifies not to warn about unresolved references and other important problems at all. The optional filter is a
regular expression; ProGuard doesn't print warnings about classes with matching names. Ignoring warnings can
be dangerous. For instance, if the unresolved classes or class members are indeed required for processing, the
processed code will not function properly. Only use this option if you know what you're doing!
-ignorewarnings
Specifies to print any warnings about unresolved references and other important problems, but to continue
processing in any case. Ignoring warnings can be dangerous. For instance, if the unresolved classes or class
members are indeed required for processing, the processed code will not function properly. Only use this

option if you know what you're doing!

-printconfiguration[filename]
Specifies to write out the entire configuration that has been parsed, with included files and replaced variables.
The structure is printed to the standard output or to the given file. This can sometimes be useful for debugging
configurations, or for converting XML configurations into a more readable format.
-dump[filename]
Specifies to write out the internal structure of the class files, after any processing. The structure is printed to the
standard output or to the given file. For example, you may want to write out the contents of a given jar file,
without processing it at all.
Class Paths ProGuard accepts a generalization of class paths to specify input files and output files. A class path
consists of entries, separated by the traditional path separator (e.g. ':' on Unix, or ';' on Windows platforms). The

order of the entries determines their priorities, in case of duplicates.

Each input entry can be:
A class file or resource file,
An apk file, containing any of the above,
A jar file, containing any of the above,
An aar file, containing any of the above,
A war file, containing any of the above,
An ear file, containing any of the above,
A zip file, containing any of the above,
A directory (structure), containing any of the above.
The paths of directly specified class files and resource files is ignored, so class files should generally be part of a
jar file, an aar file, a war file, an ear file, a zip file, or a directory. In addition, the paths of class files should not
have any additional directory prefixes inside the archives or directories.
Each output entry can be:
An apk file, in which all class files and resource files will be collected.
A jar file, in which any and all of the above will be collected,
An aar file, in which any and all of the above will be collected,
A war file, in which any and all of the above will be collected,
An ear file, in which any and all of the above will be collected,
A zip file, in which any and all of the above will be collected,
A directory, in which any and all of the above will be collected.
When writing output entries, ProGuard will generally package the results in a sensible way, reconstructing the
input entries as much as required. Writing everything to an output directory is the most straightforward option:
the output directory will contain a complete reconstruction of the input entries. The packaging can be almost
arbitrarily complex though: you could process an entire application, packaged in a zip file along with its
documentation, writing it out as a zip file again. The Examples section shows a few ways to restructure output
archives.
Files and directories can be specified as discussed in the section on file names below.
In addition, ProGuard provides the possibility to filter the class path entries and their contents, based on their
full relative file names. Each class path entry can be followed by up to 7 types of file filters between parentheses,
separated by semi-colons:
A filter for all aar names that are encountered,
A filter for all apk names that are encountered,
A filter for all zip names that are encountered,
A filter for all ear names that are encountered,
A filter for all war names that are encountered,

A filter for all jar names that are encountered,

A filter for all class file names and resource file names that are encountered.
If fewer than 7 filters are specified, they are assumed to be the latter filters. Any empty filters are ignored. More
formally, a filtered class path entry looks like this:
classpathentry([[[[[[aarfilter;]apkfilter;]zipfilter;]earfilter;]warfilter;]jarfi
lter;]filefilter)
Square brackets "[]" mean that their contents are optional.
For example, "rt.jar(java/**.class,javax/**.class)" matches all class files in the javaand javax
directories inside the rtjar.
For example, "input.jar(!**.gif,images/**)" matches all files in the imagesdirectory inside the
inputjar, except gif files.
The different filters are applied to all corresponding file types, irrespective of their nesting levels in the input;
they are orthogonal.
For example, "input.war(lib/**.jar,support/**.jar;**.class,**.gif)" only considers jar files in
the liband supportdirectories in the inputwar, not any other jar files. It then matches all class files and gif
files that are encountered.
The filters allow for an almost infinite number of packaging and repackaging possibilities. The Examples section
provides a few more examples for filtering input and output.
File Names ProGuard accepts absolute paths and relative paths for the various file names and directory names.
A relative path is interpreted as follows:
relative to the base directory, if set, or otherwise
relative to the configuration file in which it is specified, if any, or otherwise
relative to the working directory.
The names can contain Java system properties (or Ant properties, when using Ant), delimited by angular
brackets, '<' and '>'. The properties are automatically replaced by their corresponding values.
For example, <java.home>/lib/rt.jaris automatically expanded to something like
/usr/local/java/jdk/jre/lib/rt.jar. Similarly, <user.home>is expanded to the user's home
directory, and <user.dir>is expanded to the current working directory.
Names with special characters like spaces and parentheses must be quoted with single or double quotes. Each
file name in a list of names has to be quoted individually. Note that the quotes themselves may need to be
escaped when used on the command line, to avoid them being gobbled by the shell.

For example, on the command line, you could use an option like '-injars "my program.jar":"/your
directory/your program.jar"'.
File Filters Like general filters, a file filter is a comma-separated list of file names that can contain wildcards.
Only files with matching file names are read (in the case of input jars), or written (in the case of output jars). The
following wildcards are supported: ?matches any single character in a file name.*matches any part of a filename
not containing the directory separator.**matches any part of a filename, possibly containing any number of
directory separators. For example, "java/**.class,javax/**.class" matches all class files in the java
and javax.
Furthermore, a file name can be preceded by an exclamation mark '!' to exclude the file name from further
attempts to match with subsequent file names.
For example, "!**.gif,images/**" matches all files in the imagesdirectory, except gif files.
The Examples section provides a few more examples for filtering input and output.
Filters ProGuard offers options with filters for many different aspects of the configuration: names of files,
directories, classes, packages, attributes, optimizations, etc.
A filter is a list of comma-separated names that can contain wildcards. Only names that match an item on the
list pass the filter. The supported wildcards depend on the type of names for which the filter is being used, but
the following wildcards are typical:
?matches any single character in a name.*matches any part of a name not containing the package separator or
directory separator.**matches any part of a name, possibly containing any number of package separators or
directory separators.
For example, "foo,*bar" matches the name fooand all names ending with bar.
Furthermore, a name can be preceded by a negating exclamation mark '!' to exclude the name from further
attempts to match with subsequent names. So, if a name matches an item in the filter, it is accepted or rejected
right away, depending on whether the item has a negator. If the name doesn't match the item, it is tested
against the next item, and so on. It if doesn't match any items, it is accepted or rejected, depending on the
whether the last item has a negator or not.
For example, "!foobar,*bar" matches all names ending with bar, except foobar.
Overview of KeepOptions The various -keepoptions for shrinking and obfuscation may seem a bit confusing
at first, but there's actually a pattern behind them. The following table summarizes how they are related:
Keep

From being removed or

renamed

From being renamed

Classes and class members

-keep

-keepnames

Class members only

-keepclassmembers

-keepclassmembernames

Classes and class members, if class

members present

keepclasseswithmembers keepclasseswithmembernames

Each of these -keepoptions is of course followed by a specification of the classes and class members (fields
and methods) to which it should be applied.
If you're not sure which option you need, you should probably simply use -keep. It will make sure the specified
classes and class members are not removed in the shrinking step, and not renamed in the obfuscation step.

If you specify a class, without class members, ProGuard only preserves the class and its parameterless
constructor as entry points. It may still remove, optimize, or obfuscate its other class members.
If you specify a method, ProGuard only preserves the method as an entry point. Its code may still be
optimized and adapted.
Keep Option Modifiersincludedescriptorclasses
Specifies that any classes in the type descriptors of the methods and fields that the -keep option keeps should
be kept as well. This is typically useful when keeping native method names, to make sure that the parameter
types of native methods aren't renamed either. Their signatures then remain completely unchanged and
compatible with the native libraries.
allowshrinking
Specifies that the entry points specified in the -keep option may be shrunk, even if they have to be preserved
otherwise. That is, the entry points may be removed in the shrinking step, but if they are necessary after all, they
may not be optimized or obfuscated.
allowoptimization
Specifies that the entry points specified in the -keep option may be optimized, even if they have to be preserved
otherwise. That is, the entry points may be altered in the optimization step, but they may not be removed or
obfuscated. This modifier is only useful for achieving unusual requirements.
allowobfuscation
Specifies that the entry points specified in the -keep option may be obfuscated, even if they have to be
preserved otherwise. That is, the entry points may be renamed in the obfuscation step, but they may not be
removed or optimized. This modifier is only useful for achieving unusual requirements.
Class Specifications A class specification is a template of classes and class members (fields and methods). It is
used in the various -keepoptions and in the -assumenosideeffectsoption. The corresponding option is
only applied to classes and class members that match the template.
The template was designed to look very Java-like, with some extensions for wildcards. To get a feel for the
syntax, you should probably look at the examples, but this is an attempt at a complete formal definition:

[@annotationtype] [[!]public|final|abstract|@ ...] [!]interface|class|enum

classname
[extends|implements [@annotationtype] classname]
[{
[@annotationtype] [[!]public|private|protected|static|volatile|transient ...]
<fields> |
(fieldtype
fieldname);
[@annotationtype]
[[!]public|private|protected|static|synchronized|native|abstract|strictfp ...]
<methods> |
<init>(argumenttype,...) |
classname(argumenttype,...) |
(returntype methodname(argumenttype,...));
[@annotationtype] [[!]public|private|protected|static ... ] *;
...
}]
Square brackets "[]" mean that their contents are optional. Ellipsis dots "..." mean that any number of the
preceding items may be specified. A vertical bar "|" delimits two alternatives. Non-bold parentheses "()" just
group parts of the specification that belong together. The indentation tries to clarify the intended meaning, but
white-space is irrelevant in actual configuration files.
The classkeyword refers to any interface or class. The interfacekeyword restricts matches to interface
classes. The enumkeyword restricts matches to enumeration classes. Preceding the interfaceor enum
keywords by a !restricts matches to classes that are not interfaces or enumerations, respectively.
Every classname must be fully qualified, e.g. java.lang.String. Inner classes are separated by a dollar
sign "$", e.g. java.lang.Thread$State. Class names may be specified as regular expressions containing
the following wildcards: ?matches any single character in a class name, but not the package separator. For
example, "mypackage.Test?" matches "mypackage.Test1" and "mypackage.Test2", but not
"mypackage.Test12".*matches any part of a class name not containing the package separator. For
example, "mypackage.*Test*" matches "mypackage.Test" and
"mypackage.YourTestApplication", but not "mypackage.mysubpackage.MyTest". Or, more
generally, "mypackage.*" matches all classes in "mypackage", but not in its subpackages.**matches any
part of a class name, possibly containing any number of package separators. For example, "**.Test"
matches all Testclasses in all packages except the root package. Or, "mypackage.**" matches all classes
in "mypackage" and in its subpackages. For additional flexibility, class names can actually be commaseparated lists of class names, with optional !negators, just like file name filters. This notation doesn't look
very Java-like, so it should be used with moderation.

For convenience and for backward compatibility, the class name *refers to any class, irrespective of its
package.
The extendsand implementsspecifications are typically used to restrict classes with wildcards. They are
currently equivalent, specifying that only classes extending or implementing the given class qualify. Note that
the given class itself is not included in this set. If required, it should be specified in a separate option.
The @specifications can be used to restrict classes and class members to the ones that are annotated with
the specified annotation types. An annotationtype is specified just like a classname.
Fields and methods are specified much like in Java, except that method argument lists don't contain
argument names (just like in other tools like javadocand javap). The specifications can also contain the
following catch-all wildcards: <init>matches any constructor.*matches any field or method. Note that the
above wildcards don't have return types. Only the <init>wildcard has an argument list.
Fields and methods may also be specified using regular expressions. Names can contain the following
wildcards:
?matches any single character in a method name.*matches any part of a method name.
Types in descriptors can contain the following wildcards:
%

matches any primitive type ("boolean", "int", etc, but not "void").

matches any single character in a class name.

matches any part of a class name not containing the package separator.

**

matches any part of a class name, possibly containing any number of package separators.

*** matches any type (primitive or non-primitive, array or non-array).

... matches any number of arguments of any type.
Note that the ?, *, and **wildcards will never match primitive types. Furthermore, only the ***wildcards
will match array types of any dimension. For example, "** get*()" matches "java.lang.Object
getObject()", but not "float getFloat()", nor "java.lang.Object[] getObjects()".
Constructors can also be specified using their short class names (without package) or using their full class
names. As in the Java language, the constructor specification has an argument list, but no return type.
The class access modifiers and class member access modifiers are typically used to restrict wildcarded
classes and class members. They specify that the corresponding access flags have to be set for the member
to match. A preceding !specifies that the corresponding access flag should be unset.
Combining multiple flags is allowed (e.g. public static). It means that both access flags have to be set
(e.g. publicand static), except when they are conflicting, in which case at least one of them has to be set
(e.g. at least publicor protected).
ProGuard supports the additional modifiers synthetic, bridge, and varargs, which may be set by
compilers.