goopdl

Download APKs from Google Play Store using anonymous authentication. Downloads base APKs, split APKs (App Bundles), OBB expansion files, and Play Asset Delivery packs — all by default.

Hard fork. Independent project, hard-forked from appknox/gplaydl, itself a fork of rehmatworks/gplaydl. MIT licensed, upstream copyright preserved.

Install

As a global CLI tool (recommended — isolated environment, goopdl on your PATH):

uv tool install goopdl
# or
pipx install goopdl

Run it once without installing:

uvx goopdl --help

As a library or into the current environment:

pip install goopdl

Features

• Anonymous authentication via Aurora Store's token dispenser (no Google account needed)
• Optional Google account AAS token retrieval without credential or token files
• Multiple device profiles with automatic rotation for reliable token acquisition
• Downloads base APK, split APKs, OBB files, and asset packs in one go
• Streaming gzip decompression for Play Asset Delivery packs
• Beautiful terminal UI with real-time download progress bars
• Device support: ARM64, ARMv7, x86, x86_64, and Android TV
• Custom token dispenser URL support
• Search and browse app details from the command line
• Find the latest available version by sampling multiple fresh GSF IDs

Deployment / Integration

In a Dockerfile, pin an exact version (recommended for production):

RUN pip3 install goopdl==1.0.0

In a requirements.txt:

goopdl==1.0.0

To track unreleased changes, install straight from git:

pip install git+https://github.com/Villoh/goopdl.git

From source

Requirements: Python 3.9+, uv

git clone https://github.com/Villoh/goopdl.git
cd goopdl
uv sync
uv pip install .

Quick Start

# 1. Get an auth token (automatic, anonymous)
uv run goopdl auth

# 2. Download an app (base APK only)
uv run goopdl download com.whatsapp

All commands below use uv run goopdl .... If you activate the virtual environment (source .venv/bin/activate) you can drop the uv run prefix.

Commands

auth — Acquire an authentication token

goopdl auth                                   # Default (arm64)
goopdl auth --arch armv7                      # Token for older ARM devices
goopdl auth -d https://my-server/api          # Use a custom dispenser
goopdl auth --clear                           # Remove all cached tokens
goopdl auth --country IN                      # Register device with India MCC/MNC
goopdl auth --proxy socks5://host:1080        # Route dispenser call through proxy
goopdl auth --profile "Galaxy S25 Ultra"      # Use a specific device profile

Tokens are cached at ~/.config/goopdl/auth-{arch}.json and reused automatically by other commands.

Direct Google account authentication

Set both environment variables to bypass Aurora's dispenser and authenticate directly with Google:

export GOOPDL_ACCOUNT_EMAIL="account@example.com"
export GOOPDL_AAS_TOKEN="your-aas-token"
goopdl download com.whatsapp

No CLI flags, config files, or secret files are used. The AAS token is a persistent sensitive credential; changing the Google account password invalidates it. Temporary Google Play bearer tokens are kept in memory and never cached. If only one variable is configured, goopdl fails without falling back to anonymous authentication.

aastoken — Print a Google account AAS token

Password or app-password mode

# Interactive: asks for email and hides password input
goopdl aastoken

# Arguments: convenient, but password remains in shell history
goopdl aastoken user@example.com password

Google commonly rejects both account passwords and 16-character app passwords with BadAuthentication. Keep 2-Step Verification enabled and use OAuth mode instead.

Browser OAuth mode (recommended)

goopdl aastoken --browser

Sign in and select I agree in the isolated Chrome, Edge, Chromium, or Brave window that opens. goopdl captures the signed-in email and one-time oauth_token, closes the temporary browser profile, and exchanges them for the AAS token. Set GOOPDL_BROWSER to the browser executable if it is not detected automatically.

The browser profile, cookies, credentials, and tokens are never reused or saved by goopdl. The resulting AAS token is printed to the console.

Manual OAuth mode

goopdl aastoken --oauth

If browser automation is unavailable:

1. Open Google EmbeddedSetup.
2. Sign in and select I agree.
3. Open browser developer tools (F12).
4. In Chrome or Edge, open Application → Cookies → https://accounts.google.com.
5. Copy the oauth_token cookie value, which starts with oauth2_4/.
6. Run goopdl aastoken --oauth, enter the same email, then paste the token.

The oauth_token is short-lived and single-use. Credentials and tokens are used in memory only; no credentials.txt or token.txt files are created.

latest — Find the latest available version

Probes multiple fresh GSF IDs (Google Services Framework IDs) from the token dispenser. Because Google stages rollouts by device cohort (tied to the GSF ID), sampling many IDs and taking the maximum version gives the most accurate latest version available.

goopdl latest com.instagram.android
goopdl latest com.instagram.android --stable 5
goopdl latest com.instagram.android --profile "Galaxy S25 Ultra"
goopdl latest com.instagram.android --country IN
goopdl latest com.instagram.android --proxy socks5://host:1080
goopdl latest com.instagram.android -s 4 -c US -p socks5://host:1080

How the pool works: The tool maintains a regional pool of 5 GSF ID / token pairs on disk (~/.config/goopdl/token-pool-{arch}-{country}.json). Before every latest or download call, it checks how many valid (unexpired) tokens exist in that region's pool and fetches only the deficit from Aurora's dispenser — so if the pool is already full, zero dispenser calls are made. Tokens are valid for 50 minutes. If a token dies mid-request (HTTP 401), it is automatically replaced in the pool.

How convergence works: After each probe, if the best version code seen so far hasn't increased for --stable consecutive probes, the command stops early.

Output: A table with each probe's GSF ID prefix, version string, and version code. The highest version code is highlighted and printed as the final result with its version code.

download — Download APKs

By default, download fetches the base APK, all split APKs, and any additional files (OBB expansion files, Play Asset Delivery packs).

goopdl download com.whatsapp                          # Everything (base + splits + extras)
goopdl download com.whatsapp -o ./apks                # Custom output directory
goopdl download com.whatsapp -a armv7                 # ARMv7 build
goopdl download com.whatsapp -a arm64,armv7           # Several device builds
goopdl download com.google.android.katniss -a tv      # Android TV build
goopdl download com.whatsapp -v 231205015             # Specific version code
goopdl download com.instagram.android -v 434.0.0.44.74  # Specific version string
goopdl download com.whatsapp -l de,fr,zh-CN           # Extra language splits
goopdl download com.whatsapp --dm                     # DEX metadata for faster first launch
goopdl download com.whatsapp --no-splits              # Skip split APKs
goopdl download com.whatsapp --no-extras              # Skip OBB / asset packs
goopdl download com.whatsapp -d https://...           # Use custom dispenser
goopdl download com.whatsapp --country IN             # Country header for regional variant
goopdl download com.whatsapp --proxy socks5://host:1080  # Route through proxy
goopdl download com.whatsapp --profile "Galaxy S25 Ultra"  # Specific device profile

Output files:

Split APKs can be installed to a device with:

adb install-multiple com.whatsapp-231205015*.apk

Use package/version prefix shown by CLI. Bare *.apk can mix unrelated apps or versions.

info — Show app details

goopdl info com.whatsapp
goopdl info com.whatsapp --country IN
goopdl info com.whatsapp --proxy socks5://host:1080
goopdl info com.whatsapp --profile "Galaxy S25 Ultra"

Displays app name, version, developer, rating, download count, and Play Store URL.

search — Search for apps

goopdl search "whatsapp"
goopdl search "file manager" --limit 5
goopdl search "whatsapp" --country IN

list-splits — List available split APKs

goopdl list-splits com.whatsapp

Shows all split APK names (config splits, language splits, etc.) without downloading.

profiles — List device profiles

goopdl profiles           # All profiles
goopdl profiles --arch arm64   # ARM64 only
goopdl profiles --arch armv7   # ARMv7 only

Use the Key column value with --profile in any command.

Running without installing globally

After uv sync, you can also invoke via the module directly:

uv run python -m goopdl auth
uv run python -m goopdl download com.whatsapp

How It Works

1. Authentication — Gets an anonymous token from Aurora Store's dispenser, rotating through device profiles for reliability
2. Details — Fetches app metadata (version, size, splits) via Google Play's protobuf API
3. Purchase — "Purchases" the free app to get download authorization
4. Delivery — Gets download URLs for the base APK, split APKs, OBB files, and asset packs
5. Download — Streams all files in parallel from Google Play CDN with progress tracking

Finding the Latest Version

Google stages app rollouts by device cohort, which is determined by the GSF ID (Google Services Framework ID) — a device registration number assigned during token acquisition. Different GSF IDs may see different active versions (e.g. 434 vs 435 for the same app).

The latest command exploits this by sampling multiple fresh GSF IDs and reporting the highest version code seen:

goopdl latest com.instagram.android --probes 10 --stable 3

• Each probe fetches a fresh token → fresh GSF ID → queries Play Store for that cohort's version
• Probing stops early once the max version has been stable for --stable consecutive probes
• The device profile (--profile) affects which SDK level is presented; higher SDK profiles tend to receive new versions first

Token Dispenser

The tool uses Aurora Store's public token dispenser by default (https://auroraoss.com/api/auth). This service provides anonymous Google Play authentication tokens — no personal Google account required.

You can point to a custom/self-hosted dispenser with the --dispenser / -d flag on any command:

goopdl auth -d https://my-dispenser.example.com/api/auth
goopdl download com.whatsapp -d https://my-dispenser.example.com/api/auth

Device Profiles

The tool includes multiple device profiles, used to authenticate with Google Play's token dispenser. Profiles are rotated automatically during token acquisition to maximise compatibility.

Run goopdl profiles to see all available profiles and their keys. Use --profile with any command to pin a specific device.

Profiles are stored as .properties files in the goopdl/profiles/ directory.

Architecture Support

Verified integrity manifest

download --integrity-manifest PATH fails unless every requested base/split APK has Google delivery size and digest metadata. SHA-256 is preferred; SHA-1 is used only when SHA-256 is absent. Files are verified before atomic publication, then manifest is written atomically with relative filename, size, algorithm, and Base64url digest. Manifest never contains download URLs, cookies, headers, or auth tokens.