Three libraries come up when you need workflows in Python: Viewflow, SpiffWorkflow, and django-river. They solve overlapping problems in different ways, and the right choice depends on how much of the stack you want the library to own.
Short version: Viewflow is a Django-native BPMN engine you write as code; SpiffWorkflow is a framework-agnostic BPMN engine you drive from diagrams; django-river is a Django state machine you configure at runtime.
| Viewflow | SpiffWorkflow | django-river | |
|---|---|---|---|
| Framework | Django-native | Framework-agnostic | Django-native |
| Model | BPMN, code-first | BPMN, diagram-first | State machine |
| Process defined in | Python Flow class |
BPMN XML (or code) | Database / admin, at runtime |
| Parallel gateways | Yes | Yes | No (state transitions) |
| Persistence & task UI | Built in (Django ORM/views) | You build it | Django ORM + admin |
| Diagram | Rendered from code | The source of truth | None |
| DMN decision tables | No | Yes | No |
Each fits a different job.
SpiffWorkflow is a pure-Python BPMN engine. It parses full BPMN — pools and lanes, multi-instance tasks, sub-workflows, timers, signals, messages, and boundary events — and it adds DMN decision tables. The BPMN diagram is the source of truth; you author it in a designer and SpiffWorkflow executes it.
It is not tied to any web framework, which is the trade-off: it runs the process, but persistence, the user interface, and task assignment are yours to build. In a Django project you wire SpiffWorkflow in yourself.
The deeper difference is philosophy. In SpiffWorkflow the BPMN diagram is the source of truth: you draw the process in a designer, and the code executes the drawing. For a team that lives in code and version control, that extra artifact is a step away from native — the opposite of defining the flow as a Python class.
Choose SpiffWorkflow when analysts own the BPMN diagrams, you need DMN, or you are not on Django and want a standalone, framework-agnostic engine.
django-river is a Django workflow library built around a state machine you configure at runtime. States, transitions, and authorization rules live in the database, and you edit them through the admin — change the flow without a redeploy. On paper that is appealing: business users adjust the process, no engineering release needed.
In practice, that same design tends to create more problems than it removes. Because the flow lives in the database instead of in code, it sits outside version control — so you cannot test it in CI, review a change in a pull request, or promote a known-good configuration from dev to production. An edit in the admin changes production behavior on the spot, with no diff and no safety net. You pay for that convenience later, in fragility.
It also models only state transitions of a single object — no BPMN parallel branches, splits, or joins — and it has shipped no release since January 2021.
For a new project, django-river is hard to recommend. The runtime-config approach looks flexible but works against testing, review, and safe releases, and the library is dormant. A maintained, code-first engine is the safer foundation.
Viewflow is an open-source BPMN workflow engine for
Django. You define the process as a Python Flow class — with gateways,
parallel splits, and joins — and Viewflow runs it, persisting state in the Django
ORM, assigning tasks to users, and rendering the BPMN diagram from the same
code. See Python-Native BPMN for why
code-first matters.
Because it is Django-native, Viewflow already includes the parts SpiffWorkflow leaves to you: persistence, views, and task lists. For simpler needs, it also ships viewflow.fsm, a state machine without the workflow engine.
You can see it running before you install anything. demo.viewflow.io is a live Viewflow application — real workflows, task lists, and forms in a working Django app, not a slide deck or a diagram sandbox. Click through it, then read the code that produces it.
from viewflow import this
from viewflow.workflow import flow
from . import models, views
class ApprovalFlow(flow.Flow):
process_class = models.ApprovalProcess
start = flow.Start(views.RequestView.as_view()).Next(this.approve)
approve = flow.View(views.ApproveView.as_view()).Next(this.end)
end = flow.End()
Choose Viewflow when you are on Django and want code-first BPMN with persistence and a task UI included, versioned and tested like the rest of your app.
For a Django project it comes down to framework and philosophy: Viewflow’s Django-native, code-first BPMN, or a standalone engine you drive from diagrams and integrate yourself. And with Viewflow you can judge it first-hand — the live demo is one click away.
Viewflow is a Django-native BPMN engine where the process is Python code and persistence, views, and task assignment are built in. SpiffWorkflow is a framework-agnostic BPMN engine driven by BPMN diagrams, where you supply the persistence and user interface yourself. Viewflow fits Django apps; SpiffWorkflow fits standalone or non-Django use.
No. django-river is a Django state machine with runtime-configurable states, transitions, and authorization rules. It handles state transitions of an object, not BPMN processes with parallel gateways, splits, and joins.
For a Django project that needs full BPMN as code — with parallel tasks, persistence, and a task UI included — Viewflow is the most direct fit. django-river suits runtime-editable state transitions; SpiffWorkflow suits standalone BPMN execution you integrate yourself.
Yes. Viewflow defines the process as a Python class and renders the diagram from it. SpiffWorkflow also supports building workflows in code, though its primary model is a BPMN diagram. django-river uses runtime configuration rather than a BPMN diagram.