Install & Compatibility
Where this runs
tested against v2.2.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.920 runs
installs and imports cleanly · install 0.0s · import 0.565s · 82.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.504s · 83MB
76MB installed
● package 76MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Admin
✓ from flask_admin import Admin
✗ from flask.ext.admin import Admin
The `flask.ext` prefix is deprecated since Flask 0.9. Always use direct imports like `flask_admin`.
ModelView (SQLAlchemy)
✓ from flask_admin.contrib.sqla import ModelView
BaseView
✓ from flask_admin import BaseView, expose
This quickstart sets up a basic Flask application with Flask-Admin, using Flask-SQLAlchemy and a SQLite database. It defines a `User` model and registers it with the admin interface, providing instant CRUD functionality. Ensure `Flask-SQLAlchemy` is also installed for this example.
import os
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_admin import Admin
from flask_admin.contrib.sqla import ModelView
app = Flask(__name__)
app.config['SECRET_KEY'] = 'a_hard_to_guess_secret_key'
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL', 'sqlite:///admin.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)
# Define a simple model
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True, nullable=False)
def __repr__(self):
return '<User %r>' % self.name
# Create tables (if they don't exist)
with app.app_context():
db.create_all()
# Initialize Flask-Admin
admin = Admin(app, name='My Admin', template_mode='bootstrap4')
# Add views
admin.add_view(ModelView(User, db.session))
@app.route('/')
def index():
return '<p>Hello from Flask! Go to <a href="/admin/">/admin/</a> to manage users.</p>'
if __name__ == '__main__':
app.run(debug=True)
flask-admin --version
Debug
Known issues
breakingFlask-Admin dropped support for Python versions older than 3.10 starting with v2.0.0. Ensure your environment uses Python 3.10 or newer.fixUpgrade your Python environment to 3.10 or newer.
affects: >=2.0.0
breakingS3 file management (`S3FileAdmin`) has replaced the `boto` library with `boto3`. The constructor now requires an `s3_client` parameter (a `boto3.client('s3')` instance) instead of `aws_access_key_id`, `aws_secret_access_key`, and `region` parameters.fixRefactor S3FileAdmin initialization to pass a `boto3.client('s3')` instance via `s3_client`. affects: >=2.0.0
breakingAzure Blob Storage (`AzureFileAdmin`) has upgraded its SDK from legacy v2 to v12. The constructor now requires a `blob_service_client` parameter (an instance of Azure's `BlobServiceClient`) instead of a `connection_string`.fixUpdate AzureFileAdmin initialization to use a `blob_service_client` from the v12 SDK.
affects: >=2.0.0a4
deprecatedThe `flask.ext` import pattern (e.g., `from flask.ext.admin import Admin`) is deprecated and should no longer be used. Direct imports (e.g., `from flask_admin import Admin`) are the correct approach.fixChange all `from flask.ext.admin import ...` statements to `from flask_admin import ...`.
affects: <2.0.0 (legacy Flask versions), but fix applies to all.
gotchaFlask-Admin does not install database or file storage backend dependencies (e.g., SQLAlchemy, boto3, azure-storage-blob) by default. You must install these separately, often using `pip install flask-admin[extra]` or by listing them in your `requirements.txt`.fixInstall necessary optional dependencies explicitly, e.g., `pip install flask-admin[sqla]` for SQLAlchemy integration or `pip install boto3` for S3 support.
affects: All versions
gotchaWhen customizing the admin interface, fully overriding built-in templates can make future upgrades difficult. It's generally recommended to extend the existing templates rather than replacing them entirely.fixUtilize Jinja2's `{% extends '...' %}` and `{% block ... %}` features to inherit from Flask-Admin's base templates (`admin/master.html`, `admin/model/list.html`, etc.) and override only specific sections. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flask_admin'
The 'flask-admin' package is not installed in the active Python environment or is not accessible.
fixInstall the package using pip: `pip install flask-admin`
AttributeError: 'tuple' object has no attribute 'items'
This error typically arises from an incompatibility between Flask-Admin and certain versions of WTForms (especially WTForms 3.2.1 and newer), where Flask-Admin expects a dictionary-like object for form fields (e.g., Enum fields or fields using `field_flags`) but receives a tuple.
fixDowngrade WTForms to a compatible version like `WTForms==3.1.2` or ensure `field_flags` are passed as a list instead of a tuple (e.g., `field_flags=['requiredif']`).
AttributeError: module 'wtforms.validators' has no attribute 'Required'
This indicates a version incompatibility with WTForms. The `Required` validator was deprecated and renamed to `DataRequired` in WTForms versions 1.0.2 and above.
fixUpdate your form definitions to use `validators.DataRequired()` instead of `validators.Required()`.
404 Not Found (when accessing Flask-Admin pages on production)
Flask-Admin's initialization (creating the Admin instance and adding views) is often mistakenly placed inside the `if __name__ == '__main__':` block, which is not executed when the application is run by a production WSGI server.
fixMove the `Admin` instance creation and `admin.add_view()` calls outside the `if __name__ == '__main__':` block to ensure they are always registered when the application loads.
Upgrade
Version history
2.2.0latest on PyPI · released May 7, 2026
Audit
Dependencies
FlaskrequiredCore web framework dependency.
WTFormsoptionalUnderlying form handling library.
SQLAlchemyoptionalRequired for `flask_admin.contrib.sqla.ModelView` for SQL database integration.
Flask-SQLAlchemyoptionalCommon Flask extension for SQLAlchemy integration.
boto3optionalRequired for `flask_admin.contrib.s3.S3FileAdmin` for S3 file storage.
azure-storage-bloboptionalRequired for `flask_admin.contrib.azure.AzureFileAdmin` for Azure Blob storage.
Flask-BabeloptionalRequired for localization support.