# gplaydl pulls Google Play APKs, splits and OBB files down to a terminal

> gplaydl is a Python command line client that downloads Google Play packages using your own linked Google account, including split APKs, OBB expansion files and asset packs. The README is explicit that it relies on unofficial Google Play access, so account restriction is a real risk.

**rehmatworks/gplaydl** — Command Line Google Play APK downloader. Download APK files to your PC directly from Google Play Store.

- Repository: https://github.com/rehmatworks/gplaydl
- Website: https://gplaydl.com/
- Stars: 683 · Forks: 80
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/rehmatworks-gplaydl

## Why pull Play packages at all when the store is one tap away

gplaydl exists for the cases where the Play Store app cannot do the job: a server, an emulator, an Android TV box, or a CI job that needs one specific build of one specific package. The README says one command gets you the base APK, split APKs (App Bundles), OBB expansion files and Play Asset Delivery packs, which is a wider net than the typical third-party store mirror that only carries base APKs.

The tool is written in Python and packaged as a console script. The pyproject.toml declares the entry point as gplaydl = "gplaydl.cli:app", with typer for the command line surface, rich for terminal output and httpx for HTTP. The classifier in the same file marks the project as Development Status :: 4 - Beta. It also declares requires-python = ">=3.9" and a license of MIT.

Two design choices stand out. Device profiles are rotated automatically, both for authentication and for old versions that Google only serves to certain devices, and compressed transfers are used when Google Play offers them, which the README describes as often 30 to 40 percent smaller. Neither is decorative: the profile rotation is what makes version pinning work at all, and compression is decided by the server rather than by the client.

## The phone-based pairing that keeps your password off your computer

The authentication story is unusual, and it is the part you need to understand before anything else. gplaydl downloads through a Google account you add yourself in the Authenticator app. Setup requires an Android phone for a couple of minutes and a spare Google account. The README says the account stays private to you and is never shared with anyone, and that your Google password and 2FA codes never leave the phone, since the app uploads only the resulting Play token.

The pairing flow is short. You install the gplaydl Authenticator app, which is not on Google Play, so Android asks you to allow the install. You sign in with the spare account. Then you open Link gplaydl in the app and run the link command on your computer and type in the code the app shows. Once that is done, downloads go through your own account.

The README recommends a throwaway account over your main one, because Google sometimes restricts accounts it sees on unofficial clients. If you skip the link step, the first command that needs a token walks you through the same steps on its own, so the setup is not a hard prerequisite. Account management happens in the app, where you can remove an account whenever you like.

## Installing the client and taking a first package

Installation is a standard pip workflow and requires Python 3.9 or newer. The README gives two routes, and both are reproduced here exactly as documented.

```bash
pip install gplaydl
```

The source route clones the repository and installs the package from the checkout:

```bash
git clone https://github.com/rehmatworks/gplaydl.git && cd gplaydl
pip install .
```

After that, the first command is the pairing step, which asks for the code shown in the Authenticator app:

```bash
gplaydl link
```

With a linked account, a download looks like this:

```bash
gplaydl download com.whatsapp
```

The README describes that command as fetching the base APK, every split APK and any extra files unless you opt out. Every command also accepts -d/--dispenser to pick a dispenser and --arch for the device architecture. The key produced by linking is stored in ~/.config/gplaydl/config.json, and for containers and CI the README says to set GPLAYDL_API_KEY instead of linking interactively, which is the detail that decides whether this runs unattended in your pipeline.

## One download covers splits, OBB files and language packs

The output directory is where the value shows. A default download pulls the base APK, every split APK, and any extra files, which the README identifies as OBB expansion files and Play Asset Delivery packs. Naming is deterministic: the base package is written as {package}-{vc}.apk, a split as {package}-{vc}-{split}.apk, and an OBB file as {type}.{vc}.{package}.obb.

The flags let you narrow or widen that set. -o sets a custom output directory. -a selects architecture, with arm64, armv7, x86 and x86_64 available and several selectable at once, plus tv for Android TV builds. -l adds language splits on demand. --no-splits skips split APKs and --no-extras skips the OBB and asset packs, and --dm additionally fetches the DEX metadata file, a baseline profile plus vdex that the Play Store installs alongside the base APK to speed up first launch, which is optional and can be appended to adb install-multiple after the APKs.

Re-runs are incremental. A file that already exists and matches its declared hash is skipped, so the same command with an extra architecture or more languages downloads only what is missing into the same directory, and a corrupted file is noticed and fetched again. Verification happens during the stream: the base APK and every split are hashed as they arrive and checked against the SHA-256 that Google Play declares in the delivery response, so a truncated file fails at download time rather than at install time.

## Device profiles and the version codes that only some devices can see

This is where gplaydl differs from a plain file puller, and it is also where the sharp edges live. Old version codes are served by Google only to devices it considers compatible. Thirty-two-bit-only APKs are refused for sixty-four-bit-only profiles, and Android 14 plus profiles are not served APKs targeting very old SDKs. When that happens, gplaydl retries automatically with low-SDK multi-ABI device profiles until Google agrees to deliver.

Some apps are invisible to phone profiles altogether. The README gives Android TV exclusives such as com.google.android.katniss as an example, along with apps limited to one ABI family. Those are found by rotating through one device of each kind, starting with TV and then each ABI family. You can skip straight to a TV profile with -a tv, or request a TV token directly with gplaydl auth --arch tv, which is written to ~/.config/gplaydl/auth-tv.json.

Tokens follow the same pattern per architecture, landing in ~/.config/gplaydl/auth-{arch}.json and refreshing automatically before they expire. The auth subcommand exists mostly for cases where you want to check or clear that state, including gplaydl auth --clear to forget all cached tokens. If you linked more than one account in the app, --email you@gmail.com picks a specific one on auth or download, and without it gplaydl rotates through the accounts you added.

## The account risk that the README puts in bold

The most consequential line in the README is a warning, not a feature. gplaydl uses unofficial Google Play access, and Google may flag, lock or restrict accounts used with it. The README asks you to use a separate account and continue at your own risk. That means the tool's own failure mode is account loss, and it sits outside the package hashes and outside the incremental re-runs.

This shapes when the tool is the wrong choice. If you want to mirror a catalogue of hundreds of packages through CI with no human in the loop, a mechanism whose access path Google can cut off at any time is a poor foundation, particularly when the README gives no quota figures, no rate limits and no published policy on how the unofficial access behaves over time. The prohibition on Google Play distribution rights is also outside this article's scope to interpret, and that uncertainty is itself a reason to look at the alternatives before committing.

There is also a smaller detail worth knowing about when you pin versions. The version field in pyproject.toml reads 0.0.0, while the tagged releases are numbered v4.2.1, v4.2.0 and v4.1.0. Anyone automating installs should therefore rely on the tagged releases rather than on the version string reported by the packaging metadata. The last push was on 2026-09-30 and the repository is not archived, so the code itself is being changed.

## Where gplaydl sits against the store's own download path

The alternative is the route Google provides for the people it approves: an official developer or tester account with access to the app's releases, or the Play Console's own internal app sharing, which is designed for distributing a build to a bounded list of testers. Both sit inside Google's sanctioned access path and both require an approved account rather than a throwaway one.

The difference in approach is straightforward. Official paths give you a build for a specific package that you control, sometimes with Play App Signing applied, and they carry Google's own delivery guarantees. gplaydl takes the other route: it speaks the Play protocol from a client account, on your hardware, with no approval step, and it can therefore reach packages you have no publishing relationship with, in arbitrary architectures, at any version code the account's device profiles can be made to ask for. That is why it pulls split APKs, OBB files and asset packs for arbitrary packages rather than only your own release.

The cost of that flexibility is the risk noted above. gplaydl is a good fit for reproducing what a device would actually install; it is a poor fit for a distribution pipeline whose continuity you cannot control.

## Conclusion

Adopt gplaydl if you routinely need specific Google Play builds on a machine without the Play Store, such as emulators, Android TV targets or CI fixtures, and you are comfortable pairing a spare Google account through the Authenticator app. Do not adopt it for unattended bulk pipelines, since the README warns that Google may flag or restrict accounts used with unofficial clients, and skip it entirely if your Google account carries services you cannot lose. Verify first that `gplaydl link` completes on your machine, that `gplaydl download` returns a file matching the SHA-256 Play declares, and that the `pyproject.toml` version field, which reads 0.0.0 while tagged releases are numbered v4.2.1, matches the artefact your pipeline pins.

## FAQ

### How do I install gplaydl and link my Google account?

Install it with pip install gplaydl, or clone the repository and run pip install . from the checkout; Python 3.9 or newer is required. Linking needs an Android phone with the gplaydl Authenticator app, a spare Google account, and the gplaydl link command, where you type in the code shown in the app.

### What does gplaydl download besides the base APK?

By default it fetches the base APK, every split APK, OBB expansion files and Play Asset Delivery packs. You can skip parts with --no-splits and --no-extras, and add language splits with -l or architectures with -a, including arm64, armv7, x86, x86_64 and tv.

### Can I use gplaydl in CI without an interactive phone step?

Yes. The README says the key lands in ~/.config/gplaydl/config.json, and for containers and CI you should set GPLAYDL_API_KEY instead of linking interactively. Tokens are cached per architecture in ~/.config/gplaydl/auth-{arch}.json and refresh automatically before they expire.

### Is it safe to use my main Google account with gplaydl?

The README warns that the project uses unofficial Google Play access and that Google may flag, lock or restrict accounts used with it, and it recommends a separate account rather than your main one. The password and 2FA codes never leave the phone, only the resulting Play token is uploaded.

### Does gplaydl verify the files it downloads?

Yes. The base APK and every split are hashed while they stream in and checked against the SHA-256 that Google Play declares in the delivery response, so a truncated or corrupted file fails at download time. Re-runs skip files that already exist and match their declared hash.

## Sources

- [License: MIT](https://github.com/rehmatworks/gplaydl/blob/main/LICENSE)
- [Project website](https://gplaydl.com/)
- [README](https://github.com/rehmatworks/gplaydl/blob/main/README.md)
- [rehmatworks/gplaydl on GitHub](https://github.com/rehmatworks/gplaydl)
- [Releases](https://github.com/rehmatworks/gplaydl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rehmatworks-gplaydl