Registry / http-networking / httpx-oauth

httpx-oauth

JSON →
library0.17.0pypypi✓ verified 21d ago

httpx-oauth is an asynchronous OAuth client library built on top of HTTPX. It provides clients for various OAuth2 providers (GitHub, Google, Facebook, etc.) as well as a generic OAuth2 client. The library is actively maintained with a regular release cadence, including minor versions introducing new features and breaking changes, and patch versions for bug fixes and dependency updates. Current version is 0.16.1.

pip install httpx-oauth
INSTALL
IMPORT
SIG · HTTPX-OAUTH
H
httpx-oauth
http-networkingpythonv0.17.0
Install
2.2s avg
Import
209ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.17.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.216s · 22.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.2s · import 0.202s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GitHubOAuth2
from httpx_oauth.clients.github import GitHubOAuth2
GoogleOAuth2
from httpx_oauth.clients.google import GoogleOAuth2
OAuth2
from httpx_oauth.oauth2 import OAuth2
GetAccessTokenError
from httpx_oauth.exceptions import GetAccessTokenError
from httpx_oauth.oauth2 import GetAccessTokenError
As of v0.15.0, exception classes were moved to the `httpx_oauth.exceptions` module.

This quickstart demonstrates how to initialize a GitHub OAuth2 client and generate an authorization URL. It uses environment variables for client credentials, which is recommended for security. In a full application, you would capture the authorization code from the redirect URI and exchange it for an access token, then potentially fetch user profile information.

import asyncio import os from httpx_oauth.clients.github import GitHubOAuth2 async def main(): CLIENT_ID = os.environ.get('GITHUB_CLIENT_ID', 'your_github_client_id') CLIENT_SECRET = os.environ.get('GITHUB_CLIENT_SECRET', 'your_github_client_secret') REDIRECT_URI = 'http://localhost:8000/callback' client = GitHubOAuth2(CLIENT_ID, CLIENT_SECRET) authorization_url = await client.get_authorization_url( redirect_uri=REDIRECT_URI, scope=['user:email'] ) print(f"Please visit this URL to authorize: {authorization_url}") # In a real application, you would handle the redirect from GitHub # and then exchange the code for an access token. # For demonstration, we'll simulate a code. # code = "<CODE_FROM_REDIRECT_URL>" # token_data = await client.get_access_token(code, REDIRECT_URI) # print("Access Token Data:", token_data) # Example of fetching user profile (requires access token) # if 'access_token' in token_data: # user_profile = await client.get_profile(token_data['access_token']) # print("User Profile:", user_profile) if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingPython 3.8 support was dropped in `v0.16.0`. Users on Python 3.8 or older must upgrade their Python version or stay on `httpx-oauth<0.16.0`.
fix
Upgrade Python to 3.9+ or pin `httpx-oauth` to `<0.16.0`.
affects: >=0.16.0
breakingAll exception classes were moved from `httpx_oauth.oauth2` (and similar modules) to `httpx_oauth.exceptions`. Additionally, these exceptions now require a `message` property during instantiation.
fix
Update import paths for exceptions (e.g., `from httpx_oauth.exceptions import GetAccessTokenError`) and ensure `message` is passed when raising them.
affects: >=0.15.0
gotchaOlder versions of `httpx-oauth` had strict upper bound constraints on `httpx` (e.g., `<0.28`). If you are upgrading `httpx` but not `httpx-oauth`, you might encounter dependency conflicts. `v0.16.1` removed the upper bound, allowing it to work with newer `httpx` versions.
fix
Upgrade `httpx-oauth` to `0.16.1` or newer to remove the `httpx` upper bound constraint. If on an older version, ensure your `httpx` version adheres to the `httpx-oauth`'s specified range.
affects: <0.16.1
gotchaThe `get_profile` method on OAuth2 clients (e.g., `GitHubOAuth2.get_profile`) was introduced in `v0.16.0`. Attempts to use this method on earlier versions will result in an `AttributeError`.
fix
Upgrade `httpx-oauth` to `0.16.0` or newer to use the `get_profile` method. For older versions, you would need to implement the profile fetching logic manually using the `httpx` client.
affects: <0.16.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'httpx_oauth'
The `httpx-oauth` library is not installed in your Python environment, or there is a typo in the import statement (e.g., using a hyphen instead of an underscore in `httpx-oauth` when importing).
fix
Install the library using pip: `pip install httpx-oauth`. Ensure your import statements use `httpx_oauth` (with an underscore), not `httpx-oauth`.
AttributeError: 'GitHubOAuth2' object has no attribute 'get_profile'
The `get_profile` method was introduced in `httpx-oauth` version `0.16.0`. This error occurs if you are attempting to use this method with an older version of the library.
fix
Upgrade `httpx-oauth` to version `0.16.0` or newer: `pip install --upgrade httpx-oauth`.
{'error': 'invalid_grant', 'error_description': '...'}
This error originates from the OAuth provider (e.g., Google) and indicates that the authorization grant (e.g., authorization code or refresh token) is invalid, expired, revoked, or has been used already. Common reasons include using an expired authorization code, reusing a single-use authorization code, or a revoked refresh token.
fix
Ensure you exchange authorization codes immediately upon receipt, do not reuse them, and handle refresh token expiration/revocation gracefully by prompting the user to re-authenticate when this error occurs. Check your OAuth provider's console (e.g., Google Cloud Console) for any misconfigurations or revoked grants.
ImportError: cannot import name 'GetAccessTokenError' from 'httpx_oauth.oauth2'
In `httpx-oauth` version `0.16.0`, all exception classes were moved from specific modules like `httpx_oauth.oauth2` to a centralized `httpx_oauth.exceptions` module.
fix
Update your import paths for exceptions. For example, change `from httpx_oauth.oauth2 import GetAccessTokenError` to `from httpx_oauth.exceptions import GetAccessTokenError`.
Upgrade
Version history
0.17.0latest on PyPI · released May 13, 2026
Audit
Dependencies
httpxrequiredCore HTTP client library, required for all operations.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
httpx-oauth — pip install httpx-oauth · libregistry