Registry / web-framework / flask-session

flask-session

JSON →
library0.8.0pypypi✓ verified 31d ago

Flask-Session is an official extension for Flask that provides support for server-side session management. Instead of storing session data directly in client-side cookies (which can be size-limited and less secure), it stores it on the server using various backends like Redis, Memcached, FileSystem, MongoDB, SQLAlchemy, or DynamoDB. The current version is 0.8.0, and it is actively maintained by the Pallets organization, ensuring regular updates and compatibility with Flask. [1, 5, 15, 16]

pip install flask-session
INSTALL
IMPORT
SIG · FLASK-SESSION
F
flask-session
web-frameworkpythonv0.8.0
Install
2.4s avg
Import
—
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.8.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.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.6MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.000s · 24MB
22MB installed
● package 22MB
Code
Verified usage

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

Session
✓ from flask_session import Session
session
✓ from flask import session
✗ from flask_session import session
The 'Session' class from 'flask_session' is for initializing the extension; the 'session' proxy object for accessing/modifying session data comes from 'flask' itself, just like Flask's built-in session. [3, 4]

This quickstart demonstrates how to set up Flask-Session with a Redis backend. It configures the Flask application with a secret key (essential for session security) and specifies Redis as the session storage type. The example includes simple routes to set, get, and clear session data, showcasing how `flask.session` is used once `flask_session.Session` is initialized. Remember to install `redis` (`pip install 'flask-session[redis]'`) for this example to work. [3, 8]

import os from flask import Flask, session, redirect, url_for from flask_session import Session from redis import Redis app = Flask(__name__) # Configuration for server-side sessions app.config["SECRET_KEY"] = os.environ.get("FLASK_SECRET_KEY", "super-secret-key-that-should-be-random-and-long") app.config["SESSION_TYPE"] = "redis" app.config["SESSION_PERMANENT"] = False # Set to True for permanent sessions # Configure Redis client (replace with your Redis connection details) # For production, consider using environment variables for host/port/password app.config["SESSION_REDIS"] = Redis(host=os.environ.get("REDIS_HOST", "localhost"), port=6379, db=0) # Initialize Flask-Session Session(app) @app.route('/') def index(): if 'username' in session: return f'Hello, {session["username"]}! <a href="/logout">Logout</a>' return 'You are not logged in. <a href="/login">Login</a>' @app.route('/login') def login(): # Simulate a login, in a real app this would involve forms and authentication session['username'] = 'testuser' return redirect(url_for('index')) @app.route('/logout') def logout(): session.pop('username', None) return redirect(url_for('index')) if __name__ == '__main__': app.run(debug=True)
Debug
Known issues
breakingThe default session serialization format changed from `pickle` to `msgspec` in version 0.7.0. While 0.7.0 attempts to convert existing `pickle` sessions upon read/write, `pickle` support will be entirely removed in version 1.0.0. Any un-migrated `pickle` sessions will be cleared upon access in 1.0.0. [5, 7, 10]
fix
Upgrade to 0.7.0+ and ensure all active sessions are accessed/modified to trigger migration to `msgspec` before upgrading to 1.0.0. Configure `SESSION_SERIALIZATION_FORMAT = 'json'` if you need a human-readable format or have specific compatibility needs, though `msgpack` (default) is more efficient. [10]
affects: 0.7.0+
deprecatedThe `SESSION_USE_SIGNER` configuration option and `FileSystemSessionInterface` were deprecated in version 0.7.0. `FileSystemSessionInterface` is replaced by `CacheLibSessionInterface` which uses `cachelib` under the hood. [7, 10]
fix
Remove `SESSION_USE_SIGNER` from your configuration as `sid_length` now provides the relevant entropy. Migrate from `SESSION_TYPE = 'filesystem'` to `SESSION_TYPE = 'cachelib'` and ensure `cachelib` is installed. [7, 10]
affects: 0.7.0+
gotchaIt is crucial to set `app.config["SECRET_KEY"]` when using Flask-Session, even though sessions are server-side. This secret key is used to cryptographically sign the session ID cookie that is sent to the client, preventing tampering and ensuring session integrity. [8, 12]
fix
Always configure a strong, random `SECRET_KEY` in your Flask application. For production, load this from environment variables or a secure configuration system. `app.config["SECRET_KEY"] = os.environ.get("FLASK_SECRET_KEY")`
affects: All versions
gotchaFlask-Session's `Session` class is for initializing the extension with your Flask application. To access or modify the current session data within your routes, you must import and use `flask.session`, which is Flask's built-in session proxy. Attempting to use the `Session` instance directly for data access will not work as expected. [3, 4]
fix
Always use `from flask import session` and then interact with `session['key']` or `session.get('key')` within your application code after initializing Flask-Session with `Session(app)`. [3]
affects: All versions
gotchaThe `PERMANENT_SESSION_LIFETIME` configured in Flask's app config (e.g., `app.config['PERMANENT_SESSION_LIFETIME'] = timedelta(minutes=30)`) is used by Flask-Session to set the expiration time for the *server-side session data*, not just the client-side cookie. This applies regardless of whether `SESSION_PERMANENT` is set to `True` or `False`. [2, 10]
fix
Be mindful of `PERMANENT_SESSION_LIFETIME`'s impact on your server-side session data lifespan. For non-permanent sessions that expire with the browser, ensure `SESSION_PERMANENT = False` and understand its limitations regarding server-side cleanup. [10]
affects: All versions
gotchaFlask-Session does not provide a native `dynamodb` session interface or a `[dynamodb]` installation extra. Requesting `flask-session[dynamodb]` will result in a pip warning that the extra is not provided. If you need DynamoDB support, you may need to use a separate extension or implement a custom session interface.
fix
Avoid requesting `flask-session[dynamodb]` as an extra. Consult the official Flask-Session documentation for supported backends and installation extras. If DynamoDB integration is required, explore third-party extensions or implement a custom session interface using `boto3`.
affects: All versions
Errors
Common errors & fixes
RuntimeError: The session is unavailable because no secret key was set. Set the secret_key on the application to something unique and secret.
Flask's session mechanism, which Flask-Session relies on, requires a secret key for cryptographic signing of session cookies to ensure their integrity and authenticity. This error occurs when `app.secret_key` is not set or not configured correctly before the session is accessed.
fix
Set a strong, unique, and secret key in your Flask application configuration. It's best practice to load this from an environment variable for production.
```python
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_super_secret_key_here' # In production, load from env var
# Or, for Flask 0.10 and later:
# app.secret_key = 'your_super_secret_key_here'
```
RuntimeError: The session is unavailable because no SESSION_TYPE is configured.
When using `flask-session`, the default session interface (`NullSessionInterface`) is used if `SESSION_TYPE` is not explicitly configured, which is designed to raise an error when session operations are attempted to indicate that a proper server-side session backend hasn't been chosen.
fix
Configure the `SESSION_TYPE` in your Flask application to one of the supported backends (e.g., 'filesystem', 'redis', 'memcached', 'mongodb', 'sqlalchemy', 'cachelib').
```python
from flask import Flask
from flask_session import Session

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key'
app.config['SESSION_TYPE'] = 'filesystem' # Or 'redis', 'memcached', etc.
sess = Session()
sess.init_app(app)
```
redis.exceptions.ConnectionError: Error 10061 connecting to 127.0.0.1:6379. No connection could be made because the target machine actively refused it.
This error occurs when `flask-session` is configured to use Redis as its session backend, but the application cannot establish a connection with the Redis server. This usually means the Redis server is not running, is running on a different host/port, or a firewall is blocking the connection.
fix
Ensure the Redis server is running and accessible from your Flask application. Verify the `SESSION_REDIS` configuration points to the correct Redis instance.
```python
from flask import Flask
from flask_session import Session
from redis import Redis

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key'
app.config['SESSION_TYPE'] = 'redis'
app.config['SESSION_REDIS'] = Redis(host='localhost', port=6379, db=0)
sess = Session()
sess.init_app(app)
```
Also, check your Redis server status (e.g., `redis-cli ping` or `sudo systemctl status redis`) and firewall rules.
ModuleNotFoundError: No module named 'flask_session'
This error indicates that the `flask-session` library has not been installed in the Python environment where your Flask application is being run, or it was installed for a different Python version/environment.
fix
Install `flask-session` using pip in your active Python environment. If using a virtual environment, ensure it's activated.
```bash
pip install Flask-Session
# If using Python 3 and have multiple Python versions:
pip3 install Flask-Session
```
Flask sessions don't persist data / Session data disappears across requests
While not a specific error message, this common problem happens when Flask-Session is not configured correctly, leading to session data not being retained between HTTP requests. Common causes include missing `SECRET_KEY`, incorrect `SESSION_TYPE` setup, issues with how the application is run (e.g., not loading config in WSGI), or cookie-related problems like `SESSION_COOKIE_SAMESITE` not being correctly configured for cross-site requests.
fix
Ensure `SECRET_KEY` is set and loaded correctly (especially outside `if __name__ == '__main__':` blocks for production). Confirm `SESSION_TYPE` is properly configured for a persistent backend (e.g., 'filesystem', 'redis'). If deploying with a proxy or HTTPS, set `SESSION_COOKIE_SECURE=True` and `SESSION_COOKIE_SAMESITE='Lax'` or `'None'` (if cross-site) along with a `SECRET_KEY`.
```python
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_strong_secret_key'
app.config['SESSION_TYPE'] = 'filesystem'
app.config['SESSION_PERMANENT'] = False # If you want non-permanent sessions
app.config['SESSION_COOKIE_SECURE'] = True # Use True in production with HTTPS
app.config['SESSION_COOKIE_SAMESITE'] = 'Lax' # Or 'None' with SECURE=True for cross-site
sess = Session()
sess.init_app(app)
```
Upgrade
Version history
0.8.0latest on PyPI · released Mar 26, 2024
Audit
Dependencies
FlaskrequiredCore web framework dependency for the extension.
redisoptionalRequired for RedisSessionInterface.
cacheliboptionalRequired for CacheLibSessionInterface, which replaced FileSystemSessionInterface.
pymongooptionalRequired for MongoDBSessionInterface.
SQLAlchemyoptionalRequired for SqlAlchemySessionInterface.
boto3optionalRequired for DynamoDBSessionInterface (added in v0.8.0).
Agent activity
18 hits · last 30 days
node
14
Resources