Install & Compatibility
Where this runs
tested against v2.12.4 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.796s · 33.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.3s · import 0.698s · 33MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncGoTrueClient
✓ from gotrue import AsyncGoTrueClient
✗ from gotrue import GoTrueClient
This example demonstrates how to initialize the `GoTrueClient` and perform a user sign-up operation. Remember to replace placeholder URLs and keys with your actual Supabase project details, typically loaded from environment variables. Error handling for `GoTrueAPIError` is crucial for robust applications.
import os
from gotrue import GoTrueClient, GoTrueAPIError
# Initialize with your Supabase URL and (anon or service_role) key
SUPABASE_URL = os.environ.get('SUPABASE_URL', 'YOUR_SUPABASE_URL')
SUPABASE_ANON_KEY = os.environ.get('SUPABASE_ANON_KEY', 'YOUR_SUPABASE_ANON_KEY')
try:
client = GoTrueClient(
url=f"{SUPABASE_URL}/auth/v1",
headers={
"apikey": SUPABASE_ANON_KEY
}
)
# Example: Sign up a new user
email = "test@example.com"
password = "verysecretpassword"
response = client.sign_up(email=email, password=password)
print(f"Sign-up successful: {response.user.id}")
# You can also sign in existing users
# response = client.sign_in(email=email, password=password)
# print(f"Sign-in successful: {response.session.access_token}")
except GoTrueAPIError as e:
print(f"GoTrue API Error: {e.message}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaWhen initializing `GoTrueClient`, ensure you provide the correct base URL for your Supabase Auth endpoint (e.g., `YOUR_SUPABASE_URL/auth/v1`). The `apikey` header should typically contain your Supabase 'anon' key for client-side operations, or a 'service_role' key for administrative tasks.fixAlways use `f"{SUPABASE_URL}/auth/v1"` for the `url` parameter and pass the appropriate Supabase key in the `headers` dictionary as `{"apikey": YOUR_KEY}`. affects: All versions
gotchaThe `gotrue` client does not automatically persist user sessions across application restarts. You must implement your own session storage (e.g., in a database, local storage, or a secure cookie) and load/save sessions manually using methods like `set_session` and `get_session`.fixAfter successful authentication, store the `session` object (e.g., `response.session`). On subsequent application runs, retrieve the stored session and pass it to `client.set_session(stored_session)` to resume the user's session.
affects: All versions
gotchaAuthentication methods that involve redirects (e.g., OAuth, email magic links) often require a `redirect_to` parameter. Ensure this URL is correctly configured in your Supabase project's Authentication settings and matches the URL provided in your client calls.fixPass `redirect_to='https://your-domain.com/auth/callback'` to methods like `sign_in_with_oauth` or `sign_up`. Verify that this redirect URL is whitelisted in your Supabase Auth settings.
affects: All versions
deprecatedThe `refresh_session` method and related internal session refresh logic were updated. While the core functionality remains, direct calls to `refresh_session` might behave differently or be part of a larger internal flow. Rely on the client's internal session management when possible.fixEnsure you are on the latest `gotrue` version. The client is designed to automatically refresh tokens when interacting with the API if a session is set. Focus on managing the session object itself rather than manually calling refresh if not explicitly needed.
affects: Prior to v2.10.0
Upgrade
Version history
2.12.4latest on PyPI · released Aug 8, 2025
Audit
Dependencies
httpxrequiredUsed for making HTTP requests to the GoTrue API.
pyjwtrequiredUsed for handling JSON Web Tokens (JWTs) for session management.
pydanticrequiredUsed for data validation and settings management.