Install & Compatibility
Where this runs
tested against v0.18.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
py 3.9
✕ build_error
✕ build_error
176MB installed
● package 176MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ModelForm
✓ from dash_pydantic_form import ModelForm
BaseModel, Field
✓ from pydantic import BaseModel, Field
Dash, html, callback, Input, Output
✓ from dash import Dash, html, callback, Input, Output
✗ import dash
While `import dash` works, it's common practice and often more explicit to import specific components and functions directly, especially `Dash`, `html`, `callback`, `Input`, and `Output` for application and callback definition. The library itself switched to wildcard imports for `dash` in 0.18.3, but direct imports are still recommended for user applications.
This quickstart demonstrates how to create a basic Dash application with a form generated directly from a Pydantic `BaseModel`. It includes the necessary imports, model definition, `ModelForm` instantiation in the layout, and a callback to capture and validate the submitted form data.
import os
from datetime import date
from typing import Literal
from dash import Dash, html, callback, Input, Output
from dash_pydantic_form import ModelForm
from pydantic import BaseModel, Field, ValidationError
# Define a Pydantic model
class Employee(BaseModel):
first_name: str = Field(title="First name")
last_name: str = Field(title="Last name")
office: Literal["au", "uk", "us", "fr"] = Field(title="Office")
joined: date = Field(title="Employment date")
# Initialize the Dash app
app = Dash(__name__)
# Define the app layout
app.layout = html.Div([
html.H1("Employee Form"),
ModelForm(
Employee,
aio_id="employees_form_id",
form_id="new_employee_form"
),
html.Div(id="form-output")
])
# Define a callback to process form data
@callback(
Output("form-output", "children"),
Input(ModelForm.ids.main("employees_form_id", "new_employee_form"), "data")
)
def use_form_data(form_data: dict):
if form_data is None:
return html.Pre("Waiting for form data...")
try:
employee = Employee(**form_data)
return html.Pre(f"Validated Employee: {employee.model_dump_json(indent=2)}")
except ValidationError as exc:
return html.Pre(f"Validation Error:\n{exc.errors()}\nRaw Data: {form_data}", style={'color': 'red'})
if __name__ == '__main__':
app.run(debug=True)
Debug
Known issues
breakingThe library explicitly requires Pydantic V2. Using Pydantic V1 will lead to incompatibility issues and errors.fixEnsure `pydantic>=2.0.0` is installed in your environment.
affects: <0.1.0 (earlier versions not Pydantic V2 compatible), all versions requiring Pydantic 2+
deprecatedDirectly passing `repr_type` and `repr_kwargs` to `pydantic.Field` is deprecated. For future compatibility, use `json_schema_extra={'repr_type': ..., 'repr_kwargs': ...}` for customizing input rendering.fixMigrate field customizations from `Field(repr_type=..., repr_kwargs=...)` to `Field(json_schema_extra={'repr_type': ..., 'repr_kwargs': ...})`. affects: All versions where Pydantic's `Field` `extras` keyword arguments are deprecated, roughly `0.17.x` and above.
gotchaFor versions 0.15.0 and above, when using list fields with accordion or modal titles, you might need to define the `__str__` method on your Pydantic models. This is due to performance improvements in `MATCH` callbacks setting `prevent_initial_call`, affecting how initial names are displayed.fixDefine a `__str__` method on your Pydantic models that are used in list fields to ensure correct initial titles in accordions/modals.
affects: 0.15.0 and later.
gotchaConditional field visibility operates client-side and requires a specific 3-tuple format `(field, operator, value)`. Python lambda functions or direct Python logic for visibility conditions are not supported.fixAdhere to the `(field, operator, value)` tuple format for defining conditional visibility in `Field` arguments (e.g., `Field(visible=('status', '==', 'active'))`). affects: All versions.
gotchaEarlier versions (prior to 0.17.5) had known issues with multiple `ModelForm` instances on a single page causing update problems. While fixed, it's a complexity to be aware of in large applications.fixEnsure you are using version 0.17.5 or later if you plan to have multiple `ModelForm` instances on the same Dash page.
affects: <0.17.5
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dash_pydantic_form'
The `dash-pydantic-form` library is not installed in the active Python environment or there's a typo in the import statement.
fixEnsure the library is installed using pip: `pip install dash-pydantic-form`.
from dash_pydantic_form.form import ModelForm
Developers might assume `ModelForm` resides in a sub-module like `form` due to common package structures, but it's directly available at the top level of the `dash_pydantic_form` package.
fixThe correct import statement is: `from dash_pydantic_form import ModelForm`
pydantic.ValidationError: (some validation errors detailed here)
Data submitted through the generated form does not conform to the schema defined by the Pydantic model, leading to validation failure.
fixCatch the `ValidationError` in your Dash callback and process `exc.errors()` to display user-friendly messages for each invalid field, or ensure the input data matches the model's expected types and constraints before passing it to the Pydantic model constructor.
AttributeError: 'SomePydanticModel' object has no attribute '__fields_set__'
This error typically occurs when a developer overrides the `__init__` method in a Pydantic `BaseModel` subclass without calling `super().__init__(**kwargs)`, which prevents Pydantic from properly initializing its internal attributes like `__fields_set__`.
fixIf you need to customize the `__init__` method in your Pydantic model, always call `super().__init__(**kwargs)` to ensure proper Pydantic initialization: `def __init__(self, **data): super().__init__(**data)`.
Upgrade
Version history
0.18.3latest on PyPI · released Jan 31, 2026
Audit
Dependencies
pydanticrequiredRequires Pydantic V2 for model definition and validation.
dashrequiredCore dependency for building Dash applications.
dash-mantine-componentsrequiredUsed for rendering the underlying UI components of the form.