Repository navigation
Releases
v2.0.3
Full Changelog: v2.0.2...v2.0.3
v2.0.2
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
goopdl 2.0.0
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.loginreads 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 inaccount.jsoninstead and goopdl says so.--insecure-storageskips the keyring. account.jsonis0600in the0700config 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 statusshows the mode (environment, saved account, anonymous), the account and where the token is. It never prints a token.goopdl auth logoutremoves the keyring entry, the file and every cached token;goopdl auth clear-cacheremoves the cached tokens and device registrations and keeps the account.GOOPDL_ACCOUNT_EMAILandGOOPDL_AAS_TOKENstill work and win over a saved account.login --printprints only the AAS token, on one line, and saves nothing:TOKEN=$(goopdl auth login --print).login --manualopens your usual browser and asks you to paste theoauth_tokencookie, for when the browser capture doesn't work.- From Python, a
Clientnever readsaccount.json, the keyring or the environment variables: withoutcredentialsit is anonymous.import goopdldoes not loadkeyring.
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,CredentialsandDownloadResult. AClienthas its own cache directory, account, country, proxy, architecture and profile; its methods aredetails,search,list_splits,item,delivery,download, the asyncadownload, andclear_cache.download_files(): async downloads withon_progress,max_concurrentand an injectablehttpx.AsyncClient. If one download fails or the call is cancelled, the others are cancelled and their.partfiles removed.GoopdlErroras the root of every goopdl exception, plusNetworkError,MalformedResponseError,InvalidPackageError,InvalidArchError,PoolBusyError,DispenserRateLimitedError,DispenserUnavailableErrorandDownloadError.py.typedand__all__.raise_on_erroron 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 (
gsfIdand the registration tokens) is stored under the cache directory asdirect-device-<hash>-…json, mode 0600, so several processes register once. The AAS token, the access token, thetoccookie 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.detailscalls in a row made one check-in, one device upload, one sign-in and onetoc; 8 cold threads made one check-in; a new process made none and reused the same device;Client.downloadproduced 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_detailscall 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_tokentry every one of the 19 profiles. A 429 stops at the first one. - A delivery
Retry-Afterabove 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.
searchcould return a layout block (the Play Pass banner) as an app namedfbtag;playpass....goopdl aastokenwrapped 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...
v1.4.1
What's Changed
Full Changelog: v1.4.0...v1.4.1
v1.4.0
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
v1.3.0
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.0What'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
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
What's Changed
Full Changelog: v1.2.0...v1.2.1