Install & Compatibility
Where this runs
tested against v7.1.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.910 runs
installs and imports cleanly · install 0.0s · import 0.843s · 53.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.783s · 51MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
make_github_blueprint
✓ from flask_dance.contrib.github import make_github_blueprint
Commonly used preset blueprint for GitHub.
github
✓ from flask_dance.contrib.github import github
Context local for making requests to GitHub API; similar imports exist for other providers (e.g., `google`, `facebook`).
OAuth2ConsumerBlueprint
✓ from flask_dance.consumer import OAuth2ConsumerBlueprint
For creating custom OAuth 2.0 blueprints not covered by presets.
OAuthConsumerMixin
✓ from flask_dance.consumer.storage.sqla import OAuthConsumerMixin
Used with SQLAlchemy for defining the OAuth token model.
SQLAlchemyStorage
✓ from flask_dance.consumer.storage.sqla import SQLAlchemyStorage
Used to configure SQLAlchemy as the token storage backend.
This quickstart demonstrates setting up a Flask application with GitHub OAuth using Flask-Dance. It registers a GitHub blueprint, which handles the OAuth flow. The root route checks if the user is authorized; if not, it redirects them to the GitHub login page. Once authorized, it fetches and displays the GitHub username. Ensure to set `FLASK_SECRET_KEY`, `GITHUB_OAUTH_CLIENT_ID`, and `GITHUB_OAUTH_CLIENT_SECRET` environment variables. For local development without HTTPS, `OAUTHLIB_INSECURE_TRANSPORT=1` must be set.
import os
from flask import Flask, redirect, url_for, session
from flask_dance.contrib.github import make_github_blueprint, github
app = Flask(__name__)
app.secret_key = os.environ.get("FLASK_SECRET_KEY", "supersekrit")
github_blueprint = make_github_blueprint(
client_id=os.environ.get("GITHUB_OAUTH_CLIENT_ID"),
client_secret=os.environ.get("GITHUB_OAUTH_CLIENT_SECRET"),
)
app.register_blueprint(github_blueprint, url_prefix="/login")
@app.route("/")
def index():
if not github.authorized:
return redirect(url_for("github.login"))
resp = github.get("/user")
assert resp.ok, resp.text
return f"You are @{resp.json()['login']} on GitHub"
if __name__ == "__main__":
# For local development with HTTP, set OAUTHLIB_INSECURE_TRANSPORT=1
# Example: export OAUTHLIB_INSECURE_TRANSPORT=1
app.run(debug=True)
Debug
Known issues
breakingFlask-Dance v7.0.0 removed the Twitter pre-set configuration and introduced support for Authorization Flow with PKCE. Existing Twitter integrations will break and require manual implementation or updating to a custom blueprint. Dexcom preset was added.fixFor Twitter, migrate to a custom blueprint or an alternative library. Review documentation for Dexcom integration and PKCE if applicable.
affects: 7.0.0 and above
breakingVersion 6.0.0 updated minimum supported versions to Flask 2.0.3 and Werkzeug 2.1. Version 5.0.0 also dropped support for Flask versions below 1.0.4, specifically adding support for Flask 2.0. Ensure your Flask and Werkzeug versions are compatible.fixUpgrade Flask to 2.0.3+ and Werkzeug to 2.1+ to ensure compatibility with Flask-Dance 6.x and 7.x.
affects: 5.0.0 and above
breakingFlask-Dance v4.0.0 dropped support for Python 2.7. It also added support for SQLAlchemy 1.4. Older Python 2.7 applications must be migrated to Python 3.fixUpgrade your application's Python version to 3.6+.
affects: 4.0.0 and above
breakingOlder versions (pre-v1.0.0, specifically in 0.x releases) had breaking changes in how backends worked, including changes to `OAuthConsumerMixin` columns setting `nullable=False`, which could require database migrations if upgrading from very old versions. Additionally, the attribute to store the backend changed from `backend` to `storage`.fixConsult `CHANGELOG.rst` for specific migration steps if upgrading from very old versions. Ensure `blueprint.storage = ...` is used instead of `blueprint.backend = ...`.
affects: Pre-1.0.0 to 1.x (and related documentation)
gotchaFor local development over HTTP (non-HTTPS), you must set the `OAUTHLIB_INSECURE_TRANSPORT` environment variable to `1`. However, this should NEVER be used in production environments, as it disables security checks and makes your application vulnerable.fixSet `export OAUTHLIB_INSECURE_TRANSPORT=1` for local testing. Always use HTTPS in production and remove this environment variable.
affects: All versions
gotchaAn open issue (#438 on GitHub) indicates that `oauthlib` version 3.3.0 breaks the current implementation of Flask-Dance, preventing OAuth flows from working correctly. This is a critical dependency issue.fixDowngrade `oauthlib` to a compatible version (e.g., `oauthlib<3.3.0`) until Flask-Dance officially supports `oauthlib==3.3.0` or a fix is released. Monitor the Flask-Dance GitHub issues for updates.
affects: All versions using oauthlib==3.3.0
Errors
Common errors & fixes
Error: redirect_uri_mismatch
This error often occurs when the redirect URI configured in your OAuth provider (e.g., Google, GitHub) does not exactly match the URI generated by Flask-Dance, frequently due to a mismatch between HTTP and HTTPS protocols, especially when running behind a proxy server.
fixEnsure the callback URL registered with your OAuth provider (e.g., in Google Cloud Console or GitHub OAuth settings) precisely matches the URL Flask-Dance generates, including the protocol (http:// or https://). If behind a proxy, use `werkzeug.middleware.proxy_fix.ProxyFix` to correctly inform Flask about the forwarded protocol: `from werkzeug.middleware.proxy_fix import ProxyFix; app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1)`.
ModuleNotFoundError: No module named 'flask_dance'
This error means the `flask-dance` package is not installed or not accessible in the Python environment where your application is being executed.
fixInstall the `flask-dance` library using pip: `pip install Flask-Dance`. If you're using specific storage backends like SQLAlchemy, install with `pip install Flask-Dance[sqla]`. If deploying, ensure the dependency is correctly listed in your `requirements.txt` and installed during the deployment process (e.g., in a Dockerfile).
ModuleNotFoundError: No module named 'flask_dance.consumer.backend'
This specific `ModuleNotFoundError` is a result of a breaking change introduced in Flask-Dance 2.0.0, where the 'backend' module was renamed to 'storage'.
fixUpdate your import statements to use 'storage' instead of 'backend'. For example, change `from flask_dance.consumer.backend.sqla import SQLAlchemyBackend` to `from flask_dance.consumer.storage.sqla import SQLAlchemyStorage`.
AttributeError: 'OAuth2ConsumerBlueprint' object has no attribute 'get'
This error occurs when you attempt to make an HTTP request directly on the `OAuth2ConsumerBlueprint` object (e.g., `github.get(...)`) instead of using its `session` attribute. The blueprint itself is not a Requests session object.
fixAccess the Requests session through the `.session` attribute of the blueprint. For example, change `github.get('/user')` to `github.session.get('/user')`. oauthlib.oauth2.rfc6749.errors.MismatchingStateError: (mismatching_state) CSRF Warning! State not equal in request and response.
This error indicates a Cross-Site Request Forgery (CSRF) protection failure. The `state` parameter, which is used to protect against CSRF attacks, was either not sent, did not match, or was lost between the authorization request and the callback from the OAuth provider. This can happen due to session issues, aggressive browser settings, or misconfigured proxies.
fixEnsure Flask's session is correctly configured and working, especially when behind proxies (using `ProxyFix`). Verify that `app.secret_key` is set. In some development environments or specific proxy setups, setting the environment variable `OAUTHLIB_INSECURE_TRANSPORT=1` can bypass the HTTPS requirement enforced by oauthlib, but this should *only* be used for local testing.
Upgrade
Version history
7.1.0latest on PyPI · released Mar 5, 2024
Audit
Dependencies
FlaskrequiredCore web framework integration.
requestsrequiredUsed for making HTTP requests to OAuth providers.
oauthlibrequiredHandles the underlying OAuth protocol logic.
Flask-SQLAlchemyoptionalOptional, for SQLAlchemy token storage.
PythonrequiredRequires Python 3.6 or higher.