The `apksigner` tool, available in revision 24.0.3 and higher of
the Android SDK Build Tools, lets you sign APKs and confirm that an
APK's signature will be verified successfully on all versions of the Android
platform supported by that APK.

This page presents a short guide for using
the tool and serves as a reference for the different command-line options that
the tool supports. For a more complete description of how the
`apksigner` tool is used for signing your APKs, see [Sign your app](https://developer.android.com/studio/publish/app-signing).


**Caution:** If you sign your APK using `apksigner`
and make further changes to the APK, the APK's signature is invalidated.
If you use
[`zipalign`](https://developer.android.com/studio/command-line/zipalign) to align
your APK, use it before signing the APK.

## Usage

### Sign an APK


The syntax for signing an APK using the `apksigner` tool is as
follows:  

```
apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk
```


When you sign an APK using the `apksigner` tool, you must provide
the signer's private key and certificate. You can include this information in
two ways:

- Specify a KeyStore file using the `--ks` option.
- Specify the private key file and certificate file separately using the `--key` and `--cert` options, respectively. The private key file must use the PKCS #8 format, and the certificate file must use the X.509 format.


Usually, you sign an APK using only one signer. If you need to
sign an APK using multiple signers, use the `--next-signer` option
to separate the set of [general options](https://developer.android.com/tools/apksigner#options-sign-general) to
apply to each signer:  

```
apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk
```

### Verify the signature of an APK


The syntax for confirming the successful verification of an APK's signature
on supported platforms is as follows:  

```
apksigner verify [options] app-name.apk
```

### Rotate signing keys

The syntax for rotating a *signing certificate lineage*, or a new sequence of
signatures, is as follows:  

```
$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks
```

## Options


The following lists include the set of options for each command that the
`apksigner` tool supports.

### Sign command

The `apksigner` sign command has the following options.

#### General options


The following options specify basic settings to apply to a signer:

`--out <apk-filename>`
:
    The location where you'd like to save the signed APK. If this option isn't
    provided explicitly, the APK package is signed in place, which overwrites
    the input APK file.

`--min-sdk-version <integer>`
:
    The lowest Android framework API level that `apksigner` uses to
    confirm that the APK's signature will be verified. Higher values allow the
    tool to use stronger security parameters when signing the app but limit
    the APK's availability to devices running more recent versions of Android.
    By default, `apksigner` uses the value of the
    `minSdkVersion` attribute from the app's manifest file.

`--max-sdk-version <integer>`
:
    The highest Android framework API level that `apksigner` uses
    to confirm that the APK's signature will be verified. By default, the tool
    uses the highest possible API level.

`--rotation-min-sdk-version <integer>`
:
    The lowest API level the APK's rotated signing
    key should use to produce the APK's signature. The
    original (unrotated) signing key for the APK will be used for all
    previous platform versions. By default,
    rotated signing keys, which are supported on devices that run Android 13
    (API level 33) or higher, are used with the v3.1 signing block.

`--v1-signing-enabled <true | false>`
:
    Determines whether `apksigner` signs the given APK package
    using the traditional, JAR-based signing scheme. By default, the tool uses
    the values of `--min-sdk-version` and
    `--max-sdk-version` to decide when to apply this signature
    scheme.

`--v2-signing-enabled <true | false>`
:
    Determines whether `apksigner` signs the given APK package
    using the [APK
    Signature Scheme v2](https://developer.android.com/about/versions/nougat/android-7.0#apk_signature_v2). By default, the tool uses the values of
    `--min-sdk-version` and `--max-sdk-version` to decide
    when to apply this signature scheme.

`--v3-signing-enabled <true | false>`
:
    Determines whether `apksigner` signs the given APK package
    using the [APK
    Signature Scheme v3](https://source.android.com/security/apksigning/v3). By default, the tool uses the values of
    `--min-sdk-version` and `--max-sdk-version` to decide
    when to apply this signature scheme.

`--v4-signing-enabled <true | false | only>`

:   Determines whether `apksigner` signs the given APK package
    using the [APK
    Signature Scheme v4](https://developer.android.com/about/versions/11/features#signature-scheme-v4). This scheme
    produces a signature in a separate file (<var translate="no">apk-name</var>`.apk.idsig`).
    If `true` and the APK is not signed, then a v2 or v3 signature
    is generated based on the values of `--min-sdk-version` and
    `--max-sdk-version`. The command then produces the
    `.idsig` file based on the content of the signed APK.

    Use `only` to generate only the v4
    signature without modifying the APK and any signatures
    it had before the invocation. `only` fails if the APK doesn't
    have a v2 or v3 signature already or if the signature used a different key
    than the one provided for the current invocation.

    By default, the tool uses the values of
    `--min-sdk-version` and `--max-sdk-version` to decide
    when to apply this signature scheme.

`-v`, `--verbose`
:
    Use the verbose output mode.

#### Per-signer options


The following options specify the configuration of a particular signer. These
options aren't necessary if you sign your app using only one signer.

`--next-signer <signer-options>`
:
    Used for specifying different general options for each signer.

`--v1-signer-name <basename>`
:
    The base name for the files that comprise the JAR-based signature for the
    current signer. By default, `apksigner` uses the key alias of
    the KeyStore or the basename of the key file for this signer.

#### Key and certificate options


The following options specify the signer's private key and certificate:

`--ks <filename>`
:
    The signer's private key and certificate chain reside in the given
    Java-based KeyStore file. If the filename is set to `"NONE"`,
    the KeyStore containing the key and certificate doesn't need a file
    specified, which is the case for some PKCS #11 KeyStores.

`--ks-key-alias <alias>`
:
    The name of the alias that represents the signer's private key and
    certificate data within the KeyStore. If the KeyStore associated with the
    signer contains multiple keys, you must specify this option.

`--ks-pass <input-format>`

:
    The password for the KeyStore that contains the signer's private key and
    certificate. You must provide a password to open a KeyStore. The
    `apksigner` tool supports the following formats:

    - `pass:<password>` -- Password provided inline with the rest of the `apksigner sign` command.
    - `env:<name>` -- Password is stored in the given environment variable.
    - `file:<filename>` -- Password is stored as a single line in the given file.
    - `stdin` -- Password is provided as a single line in the standard input stream. This is the default behavior for `--ks-pass`.


    **Note:** If you include multiple passwords in the same
    file, specify them on separate lines. The `apksigner` tool
    associates passwords with an APK's signers based on the order in which
    you specify the signers. If you've provided two passwords for a signer,
    `apksigner` interprets the first password as the KeyStore
    password and the second one as the key password.

`--pass-encoding <charset>`
:
    Includes the specified character encodings, such as
    `ibm437` or `utf-8`, when trying to
    handle passwords containing non-ASCII characters.


    Keytool often encrypts keystores by converting the password using the console's default
    charset. By default, `apksigner` tries to decrypt using several forms of the
    password:
    - The Unicode form
    - The form encoded using the JVM default charset
    - On Java 8 and older, the form encoded using the console's default charset
    - On Java 9, `apksigner` cannot detect the console's charset. You may need to specify `--pass-encoding` when a non-ASCII password is used. You may also need to specify this option with KeyStores that keytool created on a different OS or in a different locale.

`--key-pass <input-format>`

:
    The password for the signer's private key, which is needed if the
    private key is password protected. The `apksigner` tool
    supports the following formats:

    - `pass:<password>` -- Password is provided inline with the rest of the `apksigner sign` command.
    - `env:<name>` -- Password is stored in the given environment variable.
    - `file:<filename>` -- Password is stored as a single line in the given file.
    - `stdin` -- Password is provided as a single line in the standard input stream. This is the default behavior for `--key-pass`.

`--ks-type <algorithm>`
:
    The type or algorithm associated with the KeyStore that contains the
    signer's private key and certificate. By default, `apksigner`
    uses the type defined as the `keystore.type` constant in the
    Security properties file.

`--ks-provider-name <name>`
:
    The name of the JCA Provider to use when requesting the signer's KeyStore
    implementation. By default, `apksigner` uses the
    highest-priority provider.

`--ks-provider-class <class-name>`
:
    The fully qualified class name of the JCA Provider to use when requesting
    the signer's KeyStore implementation. This option serves as an alternative
    for `--ks-provider-name`. By default, `apksigner`
    uses the provider specified with the `--ks-provider-name`
    option.

`--ks-provider-arg <value>`
:
    A string value to pass in as the argument for the constructor of the JCA
    Provider class; the class itself is defined with the
    `--ks-provider-class` option. By default, `apksigner`
    uses the class's zero-argument constructor.

`--key <filename>`
:
    The name of the file that contains the signer's private key. This file
    must use the PKCS #8 DER format. If the key is password protected,
    `apksigner` prompts for the password using standard input
    unless you specify a different kind of input format using the
    `--key-pass` option.

`--cert <filename>`
:
    The name of the file that contains the signer's certificate chain. This
    file must use the X.509 PEM or DER format.

### Verify command

The `apksigner` verify command has the following options.

`--print-certs`
:
    Show information about the APK's signing certificates.

`--min-sdk-version <integer>`
:
    The lowest Android framework API level that `apksigner` uses to
    confirm that the APK's signature will be verified. Higher values allow the
    tool to use stronger security parameters when signing the app but limit
    the APK's availability to devices running more recent versions of Android.
    By default, `apksigner` uses the value of the
    `minSdkVersion` attribute from the app's manifest file.

`--max-sdk-version <integer>`
:
    The highest Android framework API level that `apksigner` uses
    to confirm that the APK's signature will be verified. By default, the tool
    uses the highest possible API level.

`-v`, `--verbose`
:
    Use the verbose output mode.

`-Werr`
:
    Treat warnings as errors.

## Examples

The following are examples using `apksigner`.

### Sign an APK


Sign an APK using `release.jks`, which is the only key in the
KeyStore:  

```
$ apksigner sign --ks release.jks app.apk
```


Sign an APK using a private key and certificate stored as separate files:  

```
$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk
```


Sign an APK using two keys:  

```
$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk
```


Sign an APK with a rotated signing key and the rotation targeting SDK version 28+:  

```
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28
```


Sign an APK with a rotated signing key and the rotation targeting SDK version 33+:  

```
$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk
```

### Verify the signature of an APK


Check whether the APK's signatures are expected to be confirmed as valid on
all Android platforms that the APK supports:  

```
$ apksigner verify app.apk
```


Check whether the APK's signatures are expected to be confirmed as valid on
Android 4.0.3 (API level 15) and higher:  

```
$ apksigner verify --min-sdk-version 15 app.apk
```

### Rotate signing keys

Enable a signing certificate lineage that supports key rotation:  

```
$ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks
```

Rotate your signing keys again:  

```
$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks
```