Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.637s · 29.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.6s · import 0.583s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gpsoauth
✓ import gpsoauth
perform_master_login
✓ from gpsoauth import perform_master_login
perform_oauth
✓ from gpsoauth import perform_oauth
exchange_token
✓ from gpsoauth import exchange_token
This quickstart demonstrates how to perform a master login to obtain a master token, and then use that token to acquire a service-specific authentication token. It's crucial to use an App Password if Two-Factor Authentication (2FA) is enabled on the Google account. Sensitive credentials are retrieved from environment variables for better security.
import os
import gpsoauth
# It's recommended to retrieve these from environment variables or a secure configuration.
# For a real application, avoid hardcoding sensitive data.
email = os.environ.get('GPSOAUTH_EMAIL', 'your_email@gmail.com')
password = os.environ.get('GPSOAUTH_PASSWORD', 'your_app_password') # Use an app password if 2FA is enabled
android_id = os.environ.get('GPSOAUTH_ANDROID_ID', '0123456789abcdef') # A 16-character hex device ID
try:
# Perform master login to get the master token
master_response = gpsoauth.perform_master_login(
email=email,
password=password,
android_id=android_id
)
master_token = master_response.get('Token')
if master_token:
print(f"Master Token: {master_token[:10]}...")
# Example: Perform OAuth for Google Play Music service ('sj')
auth_response = gpsoauth.perform_oauth(
email=email,
master_token=master_token,
android_id=android_id,
service='sj', # Example service: Google Play Music
app='com.google.android.music',
client_sig='38918a453d07199354f8b98840b6156e19f7dc9f' # Example signature for Google Play Music
)
auth_token = auth_response.get('Auth')
if auth_token:
print(f"Service Auth Token: {auth_token[:10]}...")
else:
print(f"Could not get service auth token. Response: {auth_response}")
else:
print(f"Could not get master token. Response: {master_response}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure your email, password (or app password), and Android ID are correct.")
print("If 2-Factor Authentication is enabled, use an App Password instead of your Google account password.")
print("Also, check if your Google account requires a browser sign-in ('NeedsBrowser' error) or if the service is disabled ('ServiceDisabled').")
Debug
Known issues
breakingVersion 2.0.0 of gpsoauth raises the minimum supported Python version to 3.9. Projects using older Python versions must upgrade or stick to gpsoauth < 2.0.0.fixUpgrade your Python environment to 3.9 or higher. If unable to upgrade Python, pin gpsoauth to a version less than 2.0.0 (e.g., `pip install 'gpsoauth<2.0.0'`).
affects: >=2.0.0
breakinggpsoauth 2.0.0 introduced breaking changes related to urllib3 compatibility. It now explicitly supports `urllib3 > 2.0`, while older versions had compatibility fixes for `urllib3 < 2`.fixEnsure your `urllib3` dependency is version 2.0 or higher. If you encounter issues, verify the `requests` library (which depends on `urllib3`) is also updated to a compatible version.
affects: >=2.0.0
gotchaWhen 2-Factor Authentication (2FA) is enabled on your Google account, `perform_master_login` will often fail with a 'BadAuthentication' error if you use your regular Google account password. You need to generate and use an App Password instead.
gotchaMany authentication failures (`BadAuthentication`, `NeedsBrowser`, `ServiceDisabled`) are due to Google's continuous changes to its authentication systems or stricter security checks. Sometimes, using the `exchange_token` flow with a manually obtained `oauth_token` cookie might be necessary.fixIf `perform_master_login` fails, try the alternative flow documented in the `gpsoauth` README, which involves obtaining an `oauth_token` cookie from a browser session and using `gpsoauth.exchange_token`. Also, ensure the `client_sig` and `service` parameters for `perform_oauth` are correct for the target Google service.
affects: All versions
Errors
Common errors & fixes
{'Error': 'BadAuthentication'}
This is a common error indicating authentication failure. It often happens if the provided email/password (or app password) is incorrect, or if 2FA is enabled and a regular password is used instead of an app-specific password. Google's stricter security measures can also trigger this.
fix1. Verify your `email` and `password` (or `app_password`). 2. If 2FA is on, generate and use an App Password. 3. Consider trying the `exchange_token` flow as an alternative. 4. Ensure your Android ID is valid and consistent.
Error: NeedsBrowser
Google sometimes requires a browser-based sign-in for new devices or unusual activity, even with correct credentials, to verify identity. This prevents programmatic login.
fixTry logging into the Google account in a web browser from the same network/IP address to clear any security prompts. If the issue persists, the `exchange_token` flow, where you manually obtain an `oauth_token` cookie after a browser login, might be the only workaround.
{'Error': 'ServiceDisabled'}
This error indicates that the Google service you are trying to access (specified by the `service` parameter in `perform_oauth`) is either disabled for the account or the request format is no longer accepted by Google.
fixCheck if the Google service is enabled for the account. Review the `gpsoauth` GitHub repository's issues or changelog for recent updates regarding `request format` changes that might address this error, as version 2.0.0 had an update to fix this issue for some services.
Upgrade
Version history
2.0.0latest on PyPI · released Jul 4, 2025
Audit
Dependencies
pycryptodomerequiredRequired for cryptographic operations to sign requests.
requestsrequiredUsed for making HTTP requests to Google's authentication endpoints.
urllib3requiredUsed by 'requests' and requires specific versions for compatibility with gpsoauth.