Metadata-Version: 2.4
Name: apkeep
Version: 1.0.1
Summary: A command-line tool for downloading APK files from various sources
Author-email: William Budington <bill@eff.org>
License: MIT
Project-URL: Homepage, https://github.com/EFForg/apkeep
Project-URL: Repository, https://github.com/EFForg/apkeep
Keywords: apk,android,google-play,fdroid,apkpure,huawei
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: tqdm>=4.66
Requires-Dist: platformdirs>=4.0
Requires-Dist: asn1crypto>=1.5
Requires-Dist: cryptography>=42
Provides-Extra: google-play
Requires-Dist: gpapi>=0.4.4; extra == "google-play"
Dynamic: license-file

# `apkeep` - A command-line tool for downloading APK files from various sources

[![PyPI](https://img.shields.io/pypi/v/apkeep.svg)](https://pypi.org/project/apkeep/)
[![MIT licensed](https://img.shields.io/pypi/l/apkeep.svg)](./LICENSE)

This is the **Python port** of [`apkeep`](https://github.com/EFForg/apkeep).
It exposes the exact same CLI surface and produces the same human-readable
and JSON output as the Rust version, while being installable from PyPI and
embeddable in any Python project.

## Installation

```shell
pip install apkeep
```

To enable Google Play downloads, install the `google-play` extra:

```shell
pip install 'apkeep[google-play]'
```

This will also install the [`gpapi`](https://pypi.org/project/gpapi/) Python
package which is used as the underlying Google Play client.

## Usage

```text
Downloads APKs from various sources

Usage: apkeep <-a app_id[@version] | -c csv [-f field] [-v version_field]> [-d download_source] [-r parallel] OUTPATH

Arguments:
  [OUTPATH]  Path to store output files

Options:
  -a, --app <app>
          Provide the ID and optionally the version of an app directly (e.g. com.instagram.android)
  -c, --csv <csv>
          CSV file to use
  -f, --field <field>
          CSV field containing app IDs (used only if CSV is specified) [default: 1]
  -v, --version-field <version_field>
          CSV field containing versions (used only if CSV is specified)
  -l, --list-versions
          List the versions available
  -d, --download-source <download_source>
          Where to download the APKs from [default: apk-pure] [possible values: apk-pure, google-play, f-droid, huawei-app-gallery]
  -o, --options <options>
          A comma-separated list of additional options to pass to the download source
  -i, --ini <ini>
          The path to an ini file which contains configuration data
      --oauth-token <google_oauth_token>
          Google oauth token, required to retrieve long-lived aas token
  -e, --email <google_email>
          Google account email address (required if download source is Google Play)
  -t, --aas-token <google_aas_token>
          Google aas token  (required if download source is Google Play)
      --auth-token <google_auth_token>
          Google auth token (alternative to aas-token, e.g., from Aurora dispenser)
      --accept-tos
          Accept Google Play Terms of Service
  -s, --sleep-duration <sleep_duration>
          Sleep duration (in ms) before download requests [default: 0]
  -r, --parallel <parallel>
          The number of parallel APK fetches to run at a time [default: 4]
  -h, --help
          Print help
  -V, --version
          Print version
```

## Examples

The simplest example is to download a single APK to the current directory:

```shell
apkeep -a com.instagram.android .
```

This downloads from the default source, APKPure, which does not require
credentials.

To download directly from the Google Play Store, you will first have to
[obtain an AAS token](https://github.com/EFForg/apkeep/blob/master/USAGE-google-play.md).
Then:

```shell
apkeep -a com.instagram.android -d google-play -e 'someone@gmail.com' -t aas_token .
```

To download from the F-Droid open source repository:

```shell
apkeep -a org.mozilla.fennec_fdroid -d f-droid .
```

Or, to download from the Huawei AppGallery:

```shell
apkeep -a com.elysiumlabs.newsbytes -d huawei-app-gallery .
```

To download a specific version of an APK (possible for APKPure or F-Droid),
use the `@version` convention:

```shell
apkeep -a com.instagram.android@1.2.3 .
```

Or, to list what versions are available, use `-l`:

```shell
apkeep -l -a org.mozilla.fennec_fdroid -d f-droid
```

## Specify a CSV file or individual app ID

You can either specify a CSV file which lists the apps to download, or an
individual app ID. If you specify a CSV file and the app ID is not specified
by the first column, you'll have to use the `--field` option as well. If you
have a simple file with one app ID per line, you can just treat it as a CSV
with a single field.

## Download Sources

You can use this tool to download from a few distinct sources:

* The Google Play Store (`-d google-play`), given an email address and AAS
  token.
* APKPure (`-d apk-pure`), a third-party site hosting APKs available on the
  Play Store.
* F-Droid (`-d f-droid`), a repository for free and open-source Android apps.
  `apkeep` verifies that these APKs are signed by the F-Droid maintainers and
  alerts the user if an APK was downloaded but could not be verified.
* The Huawei AppGallery (`-d huawei-app-gallery`), an app store popular in
  China.

## Notes on the Python port

* The CLI flags, defaults, exit codes, and the format of `--list-versions`
  output (both plaintext and JSON via `-o output_format=json`) match the
  Rust binary.
* APKPure, F-Droid (with full PKCS#7 signature + SHA1/SHA256 verification),
  and Huawei AppGallery sources are fully supported and require no extra
  dependencies beyond the base install.
* Google Play support is provided through the optional `gpapi` Python
  package. Some advanced Rust-only options (`include_dex_metadata`) are
  surfaced but log a clear notice when ignored.

## License

MIT
