Install & Compatibility
Where this runs
tested against v0.19.1 · 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 1.232s · 47.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.8s · import 1.158s · 45MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ModelForm
✓ from wtforms_alchemy import ModelForm
ModelFormField
✓ from wtforms_alchemy import ModelFormField
✗ from wtforms_alchemy.fields import ModelFormField
wrong submodule, top-level import is correct
UniqueValidator
✓ from wtforms_alchemy import UniqueValidator
Generate a WTForms form from a SQLAlchemy model.
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from wtforms_alchemy import ModelForm
Base = declarative_base()
class User(Base):
__tablename__ = 'user'
id = Column(Integer, primary_key=True)
name = Column(String(100), nullable=False)
email = Column(String(100), nullable=False)
engine = create_engine('sqlite:///')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()
class UserForm(ModelForm):
class Meta:
model = User
include = ['name', 'email']
form = UserForm()
print(form.name.label.text)
Errors
Common errors & fixes
wtforms_alchemy.exceptions.UnknownTypeException: Unknown column type: <class 'sqlalchemy.dialects.postgresql.ARRAY'>
The column type is not registered in the default type mapping.
fixAdd a type mapping in the Meta class: 'type_mapping = {ARRAY: StringField}' or similar. AttributeError: 'ModelForm' object has no attribute 'validate_unique'
UniqueValidator is not automatically added; you need to enable it explicitly.
fixSet 'validators = [UniqueValidator()]' on the field or use 'include_unique' in Meta.
ImportError: cannot import name 'ModelForm' from 'wtforms_alchemy'
Old versions may have different import paths; ensure version >=0.16.0 or install from PyPI.
fixUpgrade to latest version with 'pip install --upgrade wtforms-alchemy'.
Upgrade
Version history
0.19.1latest on PyPI · released Aug 11, 2025
Audit
Dependencies
wtformsrequiredruntime dependency for form base classes and fields
sqlalchemyrequiredrequired for model introspection and ORM support