Skip to content

Releases

v2.0.3

Choose a tag to compare

@github-actions github-actions released this 18 Nov 00:49
v2.0.3
f809dc2

Full Changelog: v2.0.2...v2.0.3

v2.0.2

Choose a tag to compare

@github-actions github-actions released this 16 Nov 11:31
v2.0.2
7d4d75a

What's Changed

  • fix(profiles): keep --arch armv7 on 32-bit-only device profiles by @Villoh in #71
  • fix(cli): report delivered ABIs in inspect-delivery --json by @Villoh in #72

Full Changelog: v2.0.1...v2.0.2

v2.0.1

Choose a tag to compare

@github-actions github-actions released this 11 Nov 23:06
v2.0.1
b66bf60

Full Changelog: v2.0.0...v2.0.1

goopdl 2.0.0

Choose a tag to compare

@github-actions github-actions released this 05 Nov 20:49
v2.0.0
bc6fe86

goopdl is now usable as a library from other Python code, including backends that run several accounts and cache directories in one process. This is a major release: some things behave differently for code that calls goopdl.api directly, and the account commands of the CLI moved under goopdl auth. Downloads, info, search, latest and the rest of the CLI keep their commands and options.

from goopdl import Client, Config

client = Client(Config(config_dir="/var/lib/svc/goopdl/tenant-a", country="US"))
details = client.details("com.whatsapp")
result = await client.adownload("com.whatsapp", "/data/apks")

Guide with the whole API, the error hierarchy, async use and a migration table: https://villoh.github.io/goopdl/docs/library/

Upgrading

pip install -U goopdl (Python 3.10 or newer; typer must be 0.16 or newer). keyring is now a required dependency, see Signing in.

Commands that moved

Before Now
goopdl auth [--arch ...] goopdl auth token [--arch ...]
goopdl auth --clear goopdl auth clear-cache (goopdl auth logout does the same and also signs out a saved account)
goopdl aastoken --browser goopdl auth login
goopdl aastoken --oauth goopdl auth login --manual
goopdl aastoken (printed AASToken: ...) goopdl auth login --print
goopdl aastoken EMAIL PASSWORD removed: Google rejects passwords and app passwords
goopdl auth status (new)

goopdl aastoken still exists as a hidden command that warns and runs auth login --print; it accepts only --browser and --oauth. goopdl auth alone now shows its help.

Library behaviour

Existing function signatures are kept and new parameters are optional. These behaviours changed:

What Before Now
Corrupt protobuf in a Play response raw ValueError / EOFError MalformedResponseError, a PlayAPIError
Package names sent to Google as given InvalidPackageError (a ValueError) if there is no dot or a bad character
Unknown arch used in cache file names InvalidArchError (a ValueError)
Transport failures in goopdl.api raw httpx exceptions NetworkError, which is still an httpx.TransportError
CDN and network failures while downloading IntegrityError DownloadError, a subclass of IntegrityError (status_code, retryable, retry_after)
purchase on HTTP 429 returned "" raises RateLimitedError
download_app with the token pool busy PlayAPIError PoolBusyError (a TimeoutError)
Cache directory always ~/.config/goopdl $GOOPDL_CONFIG_DIR, then $XDG_CONFIG_HOME/goopdl, then ~/.config/goopdl; with XDG_CONFIG_HOME set, tokens are fetched again once (export GOOPDL_CONFIG_DIR=~/.config/goopdl keeps the old ones)
Dispenser HTTP 429 with no usable token exit code 1 or 3 exit code 5, with retry_after
CDN redirects followed anywhere at most 5, HTTPS on 443, Google hosts only
goopdl.auth.console, goopdl.download.Progress and the other Rich names Rich objects deprecated (DeprecationWarning), they still work; token functions log instead of printing
Account mode and files wrote nothing writes a device registration file; goopdl auth login also writes account.json
goopdl.aastoken.fetch_aas_token took a password or a one-time oauth_token takes only an oauth2_4/... token (ValueError otherwise); encrypt_password is gone

Signing in with a Google account

goopdl auth login opens a Chromium-based browser (Chrome, Edge, Chromium or Brave; set GOOPDL_BROWSER if goopdl can't find it) with a temporary profile, captures the one-time oauth_token after you sign in, exchanges it for an AAS token and saves the account. From then on every command uses that account.

  • The token goes to the system keyring (Secret Service, Keychain or Credential Manager) under the service goopdl. login reads it back to check the keyring really stored it. If there is no keyring (servers, containers, SSH) or it returns nothing, the token is saved in account.json instead and goopdl says so. --insecure-storage skips the keyring.
  • account.json is 0600 in the 0700 config directory and holds only the email and where the token lives. On Linux and macOS goopdl refuses it if it is a symlink, not yours, or readable by others.
  • goopdl auth status shows the mode (environment, saved account, anonymous), the account and where the token is. It never prints a token. goopdl auth logout removes the keyring entry, the file and every cached token; goopdl auth clear-cache removes the cached tokens and device registrations and keeps the account.
  • GOOPDL_ACCOUNT_EMAIL and GOOPDL_AAS_TOKEN still work and win over a saved account.
  • login --print prints only the AAS token, on one line, and saves nothing: TOKEN=$(goopdl auth login --print). login --manual opens your usual browser and asks you to paste the oauth_token cookie, for when the browser capture doesn't work.
  • From Python, a Client never reads account.json, the keyring or the environment variables: without credentials it is anonymous. import goopdl does not load keyring.

The system keyring protects the token against backups and a stolen disk, not against other processes of your user on Linux and Windows. An AAS token gives full Play Store access to the account: use a throwaway one.

Added

  • Client, Config, Credentials and DownloadResult. A Client has its own cache directory, account, country, proxy, architecture and profile; its methods are details, search, list_splits, item, delivery, download, the async adownload, and clear_cache.
  • download_files(): async downloads with on_progress, max_concurrent and an injectable httpx.AsyncClient. If one download fails or the call is cancelled, the others are cancelled and their .part files removed.
  • GoopdlError as the root of every goopdl exception, plus NetworkError, MalformedResponseError, InvalidPackageError, InvalidArchError, PoolBusyError, DispenserRateLimitedError, DispenserUnavailableError and DownloadError. py.typed and __all__.
  • raise_on_error on the token functions, get_config_dir(), validate_package().
  • The library guide in English and Spanish, and syntax highlighting for code blocks on the docs site.

Account mode

With Google account credentials, every call used to sign in from scratch and register a new device on the account. It now reuses one:

  • The access token is kept in memory per process, with one sign-in shared by concurrent callers, and renewed when it expires or on the first 401.
  • The device registration (gsfId and the registration tokens) is stored under the cache directory as direct-device-<hash>-…json, mode 0600, so several processes register once. The AAS token, the access token, the toc cookie and the email are never written to it.
  • With a mocked Google Play: 8 cold threads go from 40 requests and 8 devices to 12 and 1; 50 calls in a row from 250 requests to 54; 3 cold processes make one check-in instead of 3.
  • Against Google with a throwaway account: 3 Client.details calls in a row made one check-in, one device upload, one sign-in and one toc; 8 cold threads made one check-in; a new process made none and reused the same device; Client.download produced a valid APK with the same SHA-256 as the anonymous one; the CLI run twice used the same device; clear_cache() removed the registration and the next call registered a new one.

Performance

  • Connection reuse. Synchronous requests to Google Play and to the token dispenser now reuse keep-alive connections, one HTTP client per proxy, instead of opening a new TCP and TLS connection for each call. Against Google Play, the median get_details call went from 150 to 156 ms to 89 to 92 ms once the connection is open (about 40 % less; the first call, which opens it, costs the same). Cookies stay disabled on these clients, and a stale connection is retried once only when that is safe.
  • Waiting for the token pool lock. A busy lock is polled with an exponential backoff of 1 to 50 ms and jitter instead of a fixed interval. With a warm pool and a mocked Google (no network latency), 8 threads went from 153 to 8 ms and 64 threads from 355 to 96 ms, together with the change above.

Rate limits and retries

  • After a 429 from the token dispenser, goopdl sends it nothing more until the window ends (the server's Retry-After, capped at 15 minutes, or 60 s when it does not send one). With the pool partly filled and the dispenser limiting, 50 calls used to send 50 requests; now they send 1. It is in memory, per process.
  • Transient dispenser failures (503, connection errors) get one bounded retry with a cooldown, and a persistent failure stops after two attempts; before, a 503 made fetch_token try every one of the 19 profiles. A 429 stops at the first one.
  • A delivery Retry-After above 30 s is kept on the exception (retry_after) and fails at once; before, it was dropped and the call retried after 1 s and 3 s.

Fixed

  • Two downloads of the same file at the same time could publish a truncated APK that still passed the integrity check; each download now writes to its own temporary file.
  • Truncated gzip streams and OBB or asset packs were published as complete; sizes are now enforced as the bytes arrive.
  • search could return a layout block (the Play Pass banner) as an app named fbtag;playpass....
  • goopdl aastoken wrapped the token across four lines of 80 columns when the output was not a terminal, so capturing it in a shell variable did not work.
  • The CLI crashed on a console that cannot print → or ↑ (cp1252, redirected Windows output), and on remote app titles in other scripts.
  • Failures could leave tokens, signed URLs or credentials in an exception message o...
Read more

v1.4.1

Choose a tag to compare

@github-actions github-actions released this 03 Nov 15:31
v1.4.1
1dbaece

What's Changed

Full Changelog: v1.4.0...v1.4.1

v1.4.0

Choose a tag to compare

@github-actions github-actions released this 03 Nov 15:16
v1.4.0
3a5f84c

What's Changed

  • feat: add landing page and docs site on GitHub Pages by @Villoh in #34
  • feat: move the launch video from the landing page to the README by @Villoh in #35
  • fix: remove the horizontal scroll on mobile by @Villoh in #36
  • fix: make the copy buttons on docs code blocks visible by @Villoh in #37
  • feat: use an icon for the docs copy button by @Villoh in #38
  • fix: keep the nav visible during the theme switch on mobile by @Villoh in #39
  • feat: add prebuilt binaries and one-line installers by @Villoh in #40
  • chore: release v1.4.0 by @Villoh in #41

Full Changelog: v1.3.1...v1.4.0

v1.3.1

Choose a tag to compare

@github-actions github-actions released this 28 Oct 17:20
v1.3.1
61a5617

What's Changed

  • docs: add Google non-affiliation note to README by @Villoh in #30
  • docs: rebrand logo to flat drop mark by @Villoh in #31
  • feat: add a Nix flake by @Villoh in #32
  • chore: release v1.3.1 by @Villoh in #33

Full Changelog: v1.3.0...v1.3.1

v1.3.0

Choose a tag to compare

@github-actions github-actions released this 25 Oct 13:05
v1.3.0
1e3bf64

Highlights

  • Fix integrity manifests for multi-architecture downloads: include every verified APK/DM path and do not reject OBB files or asset packs that Google serves without digests.
  • Isolate token caches by device profile, reuse warm profiles, and serialize anonymous token-pool updates across concurrent processes on Linux and Windows.
  • Generate ADB install commands from exact selected files, with safe POSIX and PowerShell quoting.
  • Correct raw developer names, report integrity failures cleanly, stop profile retries after dispenser HTTP 429, and clear all cached credentials and indexes.
  • Detect native Brave and close isolated OAuth browsers, including launcher-wrapper child processes.
  • Add reorganized English and Spanish documentation and improve badge contrast.

Requirements

Python 3.10 or newer is required.

Upgrade

uv tool upgrade goopdl
# or
python -m pip install --upgrade goopdl==1.3.0

What's Changed

  • fix(auth): isolate cached tokens by device profile by @Villoh in #15
  • fix(api): preserve developer names in raw details by @Villoh in #16
  • fix(cli): report download integrity errors cleanly by @Villoh in #17
  • fix(cli): use exact files in ADB installation tips by @Villoh in #18
  • fix(download): reuse warm profile tokens before minting by @Villoh in #19
  • fix(auth): serialize token pool transactions across processes by @Villoh in #20
  • fix(auth): stop profile retries after dispenser HTTP 429 by @Villoh in #21
  • fix(auth): clear pooled credentials and round-robin indexes by @Villoh in #22
  • fix(browser): detect native Brave and close isolated OAuth browsers by @Villoh in #23
  • fix(download): cover every architecture in the integrity manifest by @Villoh in #24
  • chore: require Python 3.10 by @Villoh in #25
  • docs: split README into guides and add Spanish translation by @Villoh in #26
  • docs: raise badge colour contrast by @Villoh in #27
  • chore: release v1.3.0 by @Villoh in #29

Full Changelog: v1.2.2...v1.3.0

v1.2.2

Choose a tag to compare

@github-actions github-actions released this 23 Oct 22:50
v1.2.2
30c43eb

What's Changed

  • ci: add cross-platform test workflow by @Villoh in #12
  • fix: avoid misleading inspect-delivery version names by @Villoh in #14

Full Changelog: v1.2.1...v1.2.2

v1.2.1

Choose a tag to compare

@github-actions github-actions released this 06 Aug 19:20
v1.2.1
36b6a7f

What's Changed

  • fix: handle Google Play HTTP 429 delivery limits by @Villoh in #11

Full Changelog: v1.2.0...v1.2.1