Install & Compatibility
Where this runs
tested against v0.31.3 · 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 1.657s · 205.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 15.0s · import 1.537s · 206MB
178MB installed
● package 178MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
init
✓ from supertokens_python import init
SessionRecipe
✓ from supertokens_python.recipe import session
EmailPasswordRecipe
✓ from supertokens_python.recipe import emailpassword
FlaskMiddleware
✓ from supertokens_python.framework.flask import get_middleware
Initializes the SuperTokens SDK with application information, connection to the SuperTokens Core, and the desired authentication recipes. It's crucial to have the SuperTokens Core service running separately and accessible via `connection_uri`.
import os
import supertokens_python
from supertokens_python.recipe import session, emailpassword
# NOTE: This example requires a running SuperTokens Core service (e.g., at http://localhost:3567)
supertokens_python.init(
app_info=supertokens_python.AppInfo(
app_name="My SuperTokens App",
api_domain="http://localhost:3001", # Your backend domain
website_domain="http://localhost:3000" # Your frontend domain
),
connection_uri=os.environ.get('SUPERTOKENS_CONNECTION_URI', 'http://localhost:3567'),
recipes=[
session.init(), # Provides session management
emailpassword.init() # Provides email/password login
]
)
# In a web framework like Flask/FastAPI/Django, you would then integrate the middleware.
# Example for Flask (requires 'supertokens-python[flask]' installed):
# from flask import Flask
# from supertokens_python.framework.flask import get_middleware
# app = Flask(__name__)
# app.register_blueprint(get_middleware())
# @app.route('/test-session')
# @session.verify_session()
# def test_session():
# s = session.get_session() # Get current session
# return f"Hello user {s.get_user_id()}"
Debug
Known issues
gotchaSuperTokens Python SDK requires a running SuperTokens Core service (separate process/container) to function. The SDK connects to this core via the `connection_uri` parameter during initialization.fixEnsure the SuperTokens Core is installed and running before starting your Python application. Refer to SuperTokens documentation for core setup instructions.
affects: All versions
breakingTimestamps related to sessions and other features now use UTC instead of server local time.fixApplications relying on session expiry or creation times in local timezones should update their logic to account for UTC timestamps. This change improves consistency across different environments.
affects: >=0.28.0
gotchaThe `cookieDomain` configuration requires careful setup, especially in production environments or when using different subdomains. `tldextract` is used to determine the appropriate domain for cookies, and its HTTP requests can be disabled.fixExplicitly configure `cookie_domain` in `session.init()` if needed. For `tldextract` HTTP requests, set `allow_unverified_http_requests_for_tld_extract=False` in `supertokens_python.init()` if your environment restricts outbound HTTP calls or for performance reasons.
affects: All versions, specifically >=0.29.0 for `tldextract` control
Errors
Common errors & fixes
HTTPConnectionPool(host='localhost', port=3567): Max retries exceeded with url: /hello (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at ...>: Failed to establish a new connection: [Errno 111] Connection refused'))
The SuperTokens Core service is not running or is not accessible at the specified `connection_uri`.
fixStart the SuperTokens Core service and ensure its port matches the `connection_uri` in your `supertokens_python.init()` call. Verify firewall rules or container network settings if running in a containerized environment.
AttributeError: module 'supertokens_python.framework' has no attribute 'flask'
The framework-specific dependency (e.g., `supertokens-python[flask]`) was not installed, or the import path is incorrect.
fixEnsure you install the package with the correct framework extra: `pip install 'supertokens-python[flask]'` for Flask, `[fastapi]` for FastAPI, etc. Then use the correct import, e.g., `from supertokens_python.framework.flask import get_middleware`.
ValueError: cookieDomain must be a super domain of 'localhost'
The `app_info.api_domain` or `app_info.website_domain` is incorrectly configured such that the cookie domain cannot be automatically determined or is invalid for the specified domains.
fixEnsure `app_info.api_domain` and `app_info.website_domain` are correctly set. For development on `localhost`, you might need to explicitly set `cookie_domain=None` or ensure your frontend and backend are on the same base domain (e.g., `localhost:3000` and `localhost:3001` usually works).
Upgrade
Version history
0.31.3latest on PyPI · released May 6, 2026
Audit
Dependencies
httpxrequiredUsed for internal API calls to the SuperTokens Core.
aiosmtpliboptionalUsed for sending emails (e.g., password reset, email verification) if email-based recipes are enabled.
tldextractrequiredUsed for extracting the top-level domain from hostnames for cookie configuration.