# iommi: forms and tables that stop fighting your Django project

> iommi is a high level framework built on Django that provides forms, tables, and a composition system for putting them into pages, with the auto configuration that turns a model into a working table in one line. The framework is at version 7.35.0 and requires Python 3.12 and Django 5.2 or newer.

**iommirocks/iommi** — Your first pick for a django power cord

- Repository: https://github.com/iommirocks/iommi
- Website: http://iommi.rocks
- Stars: 1,091 · Forks: 69
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/iommirocks-iommi

## A toolkit that takes over the view layer

iommi is described as a toolkit to build web apps faster, built on Django but going a lot further. The distinction is that iommi does not leave the parts it covers to you. It is not a set of helpers you sprinkle into views, it is a replacement for the form, table, and page layers, and the pieces it covers are the ones that get verbose in a real project.

The four things it provides are forms, tables, a composition system, and development tooling. The forms feel familiar but are described as handling growing complexity better than Django's forms. The tables are described as powerful out of the box and scaling up to arbitrary complexity. The composition system is what lets forms, menus, and tables be combined into bigger pages, and it is the part that distinguishes iommi from a plain library.

The tooling is the fourth pillar and the most unusual. The README lists live edit, jump to code, great feedback for missing select and prefetch related, and a profiler. The feedback for missing prefetch related is a distinctive touch: in iommi, a table column that traverses a relation without declaring the join will tell you so rather than silently issuing a query per row.

The framework is BSD licensed, with the package metadata declaring BSD-2-Clause, and the README says simply BSD. The version is 7.35.0, it requires Python 3.12 or newer, and it depends on Django 5.2 or later plus pyparsing. The classifiers list Django 5.2 and Django 6.0, and the project is marked as a production stable release.

## The auto configuration is the whole pitch

The example in the README is short enough to be the entire argument for the framework:

```python
class IndexPage(Page):
    title = html.h1('Supernaut')
    welcome_text = 'This is a discography of the best acts in music!'

    artists = Table(auto__model=Artist, page_size=5)
    albums = Table(
        auto__model=Album,
        page_size=5,
    )
    tracks = Table(auto__model=Album, page_size=5)


urlpatterns = [
    path('', IndexPage().as_view()),
]
```

Three tables appear on one page, each declared with a model and a page size, and there is no view function, no template, and no queryset. The result is a page with three separate tables, a header, and some text.

The keyword doing the work is auto__model. It tells iommi to derive the columns from the model, which is what turns a data class into a full table with sorting, pagination, and cell rendering. Writing out the equivalent Django table view by hand means a class-based view, a template, a table class, column definitions, and a pagination handler, and that code is the same for every model except for the model name.

The double underscore is a deliberate convention rather than a Python keyword, and it carries meaning throughout the framework. It marks a shortcut for a configuration object, which is how the same declarative style extends beyond auto configuration. The naming and the fact that iommi is written in Python with a heavy use of pyparsing, which is a parsing library, both point to a design where configuration is expressed as a path-like syntax rather than as nested function calls.

## Composition, and why pages are a first class concept

The composition system is the piece that has no direct Django equivalent, and it is what makes iommi a framework rather than a library.

In Django, a page is a template. You render a view into a template context, and the template includes whatever partials you have written. The composition of a page is therefore spread across the view, the template, and the template includes, and it is not something the framework can inspect or manipulate.

In iommi, a page is an object built from parts. The parts are forms, tables, and menus, and they are composed into bigger pages. The Part concept in the documentation and the Traversable concept that holds them together are the two abstractions that make this work, and the menu system, which is one of the documented parts alongside Table, Form, Field, Column, Cell, Header, Action, Link, and Endpoint, is a page-level component in a way that a Django template include is not.

The practical difference is that iommi can reason about the page as a whole. That is what makes the developer tooling possible. A live edit feature that lets you change a table column and see the result needs a single model of the page, and jump to code needs to map from a rendered element back to the line of Python that produced it. Neither is possible when the page is a template plus a view plus a context dictionary.

The menus are worth singling out, because a menu built from the same composition system as the rest of the page means navigation is defined in the same place as content, with the same configuration style and the same tooling.

## The toolchain, and how it runs

The development environment is described in unusual detail, and it tells you what kind of project this is.

The dev dependency group includes django-fastdev, plus parso for parsing Python source, pytest-django at 4.8.0 with pytest at 8.1.1, pytest-snapshot for snapshot testing, pytest-xdist for parallel runs, time-machine for controlling time in tests, and the pytest plugin set including pytest-sugar, pytest-cov, and coverage. There is beautifulsoup4, which is a sign that the tests parse HTML output to assert on it, flask for serving the documentation locally, furo for the Sphinx theme, gprof2dot, watchdog for file watching, and ruff at 0.3.7 for linting. The code style is black, as the badge states.

The Dockerfile is a single stage on ghcr.io/astral-sh/uv with the python3.14-trixie-slim tag, and the dependency install is deliberately separated from the source. The pyproject.toml and uv.lock are copied first and uv sync --dev --frozen runs, with a comment explaining that this is for layer caching because the source is bind-mounted at runtime.

The docker-compose file then wires up two services. The tests service builds the same image, mounts the repository at /app, and runs uv run pytest -n auto. The examples service mounts the repository and a named volume for the example database, runs the migrations with examples/manage.py migrate, and then starts the development server on port 8000 with the port published. The Makefile has the matching targets, including make test and make test-docs, and a benchmark target that can run against master for comparison.

## The parts list, and what it tells you about the scope

The Makefile's clean-docs target is an accidental inventory of the framework, because it lists every documentation file it removes. The list is worth reading as a map of the API.

The core rendering parts are Page, Fragment, Traversable, and Part. The data parts are Table, Column, Cell, Header, ColumnHeader, HeaderConfig, Container, Cells, and Style. The form parts are Form, Field, FormAutoConfig, and Action, alongside Link and Endpoint. The query parts are Query, QueryAutoConfig, and Filter. Then there are EditColumn, EditTable, EditTable's cells, Menu, MenuItem, and Asset, plus the Attrs helper.

The EditTable and EditColumn family is the part that shows the ambition. That is inline editing in the table, meaning a user can change a row from the list view, which is a feature that in a Django project is normally a separate view, a form, and a POST handler.

The AutoConfig family, FormAutoConfig and QueryAutoConfig, is the mechanism behind the auto__model shortcut. The existence of a separate Query layer with its own auto configuration tells you that iommi does not just wrap a queryset in a table, it has its own query abstraction with filters, and that the table, the form, and the query are three separately configurable things that can be composed.

The Asset part is how static files are attached, and Attrs is the attribute dictionary that runs through the whole system, which is how the styling and the data attributes reach the rendered output. The API is large, and that is the honest trade for a framework that takes over the view layer.

## Against plain Django, and against other Django form libraries

The comparison with plain Django is the one that decides the adoption, and the honest version is that iommi removes work and adds a dependency on its own model.

Plain Django wins on familiarity. Django forms and class-based views are documented exhaustively, every Django developer knows them, and the debugging story is the standard one. iommi wins on repetition. If your project has fifty list views, the difference between writing fifty table views by hand and writing fifty Table declarations is the difference between a week and an afternoon, and the auto configuration is the mechanism that delivers that.

The second comparison is with the third party Django table and form libraries, of which there are many. The difference in approach is that those libraries replace one component, typically the table, while iommi replaces forms, tables, and page composition together, and adds tooling that depends on owning the whole page. A library that gives you a good table and leaves templates to you cannot offer jump to code, because the mapping from a rendered cell back to Python does not exist in that arrangement.

The third factor is the toolchain, and it cuts both ways. django-fastdev with live edit is a genuine productivity gain for a large application, and the same machinery is overhead in a small one, because you are learning a new set of concepts to build a page that a template would have done.

The API surface is large, and the project is explicit that it goes a lot further than Django. That is a good fit for a team with many similar screens and a poor fit for a small site, and it is the same trade in both directions.

## Conclusion

Adopt iommi if your Django project has more than a handful of CRUD screens and you want tables and forms configured from a single declarative source rather than hand-written per view. Do not adopt it for a small site with a few forms, because the abstraction has a learning curve that a plain Django form does not. Verify first that your Django version is 5.2 or 6.0 and your Python is 3.12 or newer, since the framework now refuses older versions outright.

## FAQ

### What is iommi and what does it add to Django?

iommi is a high level framework built on Django that goes further than Django's own form and table layers. It provides forms that handle growing complexity, tables that are powerful out of the box, a system to compose parts like forms, menus, and tables into bigger pages, and development tools including live edit, jump to code, and a profiler.

### How do you create a table in iommi?

With auto configuration from the model, for example Table(auto__model=Artist, page_size=5). The columns are derived from the model, and the table is added to a Page class which is then routed with path('', IndexPage().as_view()).

### Which versions of Python and Django does iommi support?

The package requires Python 3.12 or newer and Django 5.2 or later, with the classifiers listing Django 5.2 and Django 6.0 and Python 3.12, 3.13, and 3.14. The runtime dependencies are pyparsing and Django.

### How do you run the iommi test suite?

The Makefile provides make test and make test-docs, and the docker-compose file defines a tests service that builds the image, mounts the repository at /app, and runs uv run pytest -n auto with pytest-xdist for parallel execution.

### What licence is iommi released under?

BSD. The package metadata declares BSD-2-Clause, and the README simply says BSD. The authors listed in the project metadata are Anders Hovmöller and Johan Lübcke.

## Sources

- [iommirocks/iommi on GitHub](https://github.com/iommirocks/iommi)
- [Issues](https://github.com/iommirocks/iommi/issues)
- [License: BSD-3-Clause](https://github.com/iommirocks/iommi/blob/master/LICENSE)
- [Project website](http://iommi.rocks)
- [README](https://github.com/iommirocks/iommi/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/iommirocks-iommi