# SpiffWorkflow: BPMN and DMN execution in Python > SpiffWorkflow is a pure-Python workflow engine for applications that need to parse BPMN diagrams, execute process logic, and integrate DMN decisions. It supports diagram-driven and code-defined workflows, but its README does not provide a standalone first-execution tutorial. **sartography/SpiffWorkflow** — A powerful workflow engine implemented in pure Python - Repository: https://github.com/sartography/SpiffWorkflow - Stars: 1,929 · Forks: 347 - Language: Python - License: LGPL-3.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/sartography-spiffworkflow ## Why SpiffWorkflow exists for Python application teams SpiffWorkflow addresses a specific gap between diagram-based process design and Python business logic. Its stated purpose is to support low-code business applications in which non-developers can describe processes in a visual BPMN diagram while developers attach Python script tasks to those diagrams. The engine can parse the diagram and execute the resulting workflow. That combination is aimed at organizations that want process definitions to remain understandable to business participants without moving the entire execution layer out of Python. The project is not restricted to that use case. The README also identifies direct Python workflows and workflows represented by an internal JSON data structure as supported approaches. This gives a team more than one modeling path: BPMN when standards-based diagrams and richer process constructs matter, or Python definitions when the workflow is naturally expressed through application code. BPMN coverage is broader than basic start, task, and end-event sequences. The listed components include pools and lanes, multi-instance tasks, sub-workflows, timer events, signals, messages, boundary events, and loops. SpiffWorkflow also has a baseline DMN implementation connected to its Python execution engine. These features make the project relevant to decision-heavy business processes, although the term baseline is important. It signals that DMN support exists, while not establishing that every DMN specification feature is implemented equally. The intended audience includes Python developers building business applications, teams that want diagram ownership to sit closer to domain experts, and engineers evaluating a BPMN engine without adopting a Java runtime. The project does not present itself as a visual editor. A repository layout with documentation, tests, Python packages, and an example CLI reference confirms that the editor workflow is external to the core package. Teams expecting installation to provide a diagram editor, hosted process designer, or complete application interface are looking at the wrong boundary. ## SpiffWorkflow parsing and execution path Based on the repository layout, SpiffWorkflow separates packaging, executable code, documentation, and tests. The `SpiffWorkflow/` package is installed as a Python library. Its `pyproject.toml` uses `setuptools` as the build backend, discovers packages matching `SpiffWorkflow*`, and includes schema files under package data. XML schema support is therefore packaged alongside the Python modules rather than treated as an unrelated external asset. For BPMN input, the documented path begins with parsing. The project depends on `lxml` for XML document parsing, and that is its only listed runtime dependency. This keeps the external dependency surface small, but it does not mean that adopting a BPMN model is free of format constraints. A process still needs to conform to the portions of BPMN represented by the parser and supported specifications. The README does not publish a complete compatibility matrix, so unsupported constructs cannot be ruled out from this documentation. Once parsed, the BPMN elements become executable workflow specifications managed by the Python engine. Tasks can contain Python script logic, while DMN decisions are integrated with that execution layer. The precise class-level data flow is not shown in the README, so it would be misleading to invent API calls or intermediate objects here. What can be confirmed is the division between XML parsing, diagram semantics, and Python execution. Direct Python and internal JSON definitions follow the same broader execution role without requiring a BPMN diagram. That makes the engine adaptable to different definition sources, but migration between them is not documented as automatic. In particular, the README does not claim that BPMN, DMN, Python-defined, and JSON-defined workflows share every feature or can be converted losslessly. ## Installing SpiffWorkflow and building a first package The repository requires Python 3.10 or later and lists Python 3.10 through 3.14 as supported classifiers. For application use, the README gives this installation command: ```bash pip install spiffworkflow ``` After installation, a reader can verify local source development rather than immediately constructing an unspecified workflow. The standard developer setup is documented as an editable install with test dependencies: ```bash pip install -e .[dev] make tests ``` The first command installs the local project and its `dev` optional dependencies. The `make tests` target then invokes Python's `unittest` discovery against the repository's test tree. A successful result should show discovered tests completing without reported failures. This verifies the package in the reader's environment, but it is not evidence about compatibility with a particular BPMN file. Readers who prefer the repository's `uv` path can use the documented commands: ```sh uv sync --extra dev make RUN='uv run' tests ``` The first command synchronizes the development environment, while the second directs the existing Makefile test target to run through `uv`. Parallel tests and coverage have separate targets: ```bash make RUN='uv run' tests-par make RUN='uv run' tests-cov ``` `tests-par` requires `unittest-parallel`, which is included in the documented development dependencies. `tests-cov` runs coverage with the package as its source. Neither command validates an application's BPMN diagrams by itself. They validate the repository's test suite under the selected environment. The README does not include a first workflow execution example. For that step, it directs readers to the documentation at `spiff.works/docs/spiffworkflow/` and the linked `spiff-example-cli` application. Inventing an API sequence would go beyond the documented evidence, so this article stops at the confirmed package installation, build, and test commands. ## BPMN breadth versus DMN and visual tooling boundaries SpiffWorkflow's strongest documented area is BPMN processing. The feature list names multiple instances, subprocess or sub-workflow behavior, events, signals, messages, timers, boundary events, and looping. These are meaningful distinctions for an engineer choosing a workflow engine because they affect whether a diagram can represent a real approval process rather than only a simple sequence. The project does not include an editor based on the listed top-level contents. The README credits BPMN.js as an external tool used in projects that embed an editor, but SpiffWorkflow itself is the parser and execution library. A team whose primary requirement is a turnkey BPMN modeling application must add an editor and determine how saved diagrams reach the Python service. The documentation excerpt does not specify that integration path. DMN support is described as a baseline implementation. That wording suggests a narrower commitment than comprehensive BPMN coverage. DMN is useful when a process needs structured decision logic, but engineers should inspect the external documentation for supported decision tables, hit policies, and expression behavior before modeling production rules. None of those details appears in the README. The alternate Python and JSON definition paths are useful when a visual model would impose unnecessary structure. They also require separate evaluation. The README does not claim feature parity between these paths and BPMN. Choosing a code-defined workflow may simplify application integration, but it can reduce the direct value for non-developers who edit diagrams, while choosing BPMN adds parsing and standards-compliance work. ## Operational limits and realistic failure points The first limitation is documentation dependency. Installation is one command, but the README sends users elsewhere for detailed usage and heavily references a separate example application. There is no complete process-loading, task-execution, serialization, or integration example in the README. That gap matters for an engine with event types, sub-workflows, and decision logic, because installation alone does not reveal the operational API. The second limitation is Python version support. The package requires Python 3.10 or later. Classifiers cover Python 3.10 through 3.14, but the presence of a classifier should not be treated as proof of identical behavior across every environment. The repository offers standard, parallel, and coverage test commands, which gives contributors defined validation paths, yet those commands do not describe an application's production topology. SpiffWorkflow is also the wrong tool when the requirement is a hosted workflow service, a complete visual modeling suite, or a database-backed application framework supplied as one product. This repository is a library and workflow framework. The documentation excerpt does not promise identity management, dashboards, hosted execution, REST endpoints, or production persistence. Invalid or unsupported XML is another case to consider. Because BPMN parsing depends on `lxml`, the process file must be valid enough for the parser and the supported BPMN components. The README does not document tolerant parsing, automatic diagram repair, or fallback behavior. Applications will also need their own persistence strategy if they must resume interrupted workflows, but the README remains silent about a built-in persistence model and restart semantics. ## Release maintenance, packaging, and LGPL obligations The repository is not archived. Its last push was on 2026-10-12, so there is a recent sign of repository activity. Releases include `v3.2.0` on 2026-08-10 and two `v3.1.3` prereleases on 2026-03-06. The prerelease labels are relevant when planning upgrades because alpha builds can carry different stability expectations from the numbered release line. The package metadata still classifies the project as `Development Status:: 4 - Beta`, which should be considered alongside the release history. Packaging is conventional for a Python library. `pyproject.toml` declares `setuptools`, reads the version from `SpiffWorkflow.version.__version__`, and uses `lxml` as the runtime dependency. The repository also contains `uv.lock`, a `Makefile`, tests, a Dockerfile, and documentation sources. The Dockerfile copies the repository into a Python 3.14 slim image, builds a wheel, and installs the generated artifact. It is a source-build recipe rather than documentation for a production orchestration setup. The declared license is `LGPL-3.0`, and the repository includes `COPYING`. That designation matters when deciding how to distribute an application that links to or incorporates the library. This article does not provide legal advice, and the LGPL contains conditions that depend on the distribution and modification model. Engineering should review `COPYING` and the project's license notices before publishing a modified or combined work. Upgrade cost is partly visible in the moving release line and partly undocumented. The repository has automated tests and several validation targets, but it does not provide an upgrade guide, migration policy, or compatibility table in the README. Applications should first verify their BPMN and DMN usage against the documentation for the selected release rather than assuming that each package upgrade is behavior-neutral. ## Where SpiffWorkflow differs from a hosted workflow platform A real alternative is a hosted BPMN workflow platform. Such a product generally supplies a visual modeler, execution service, identity integration, operational tooling, and durable storage as a service. SpiffWorkflow instead ships as a Python library with one runtime dependency and expects the adopting team to assemble its application and operational environment. The difference is architectural: a hosted platform centralizes service management, while SpiffWorkflow places process execution inside the Python codebase. Another alternative is a simple application-specific state machine. If a process is only a fixed sequence with a few approval branches, custom state fields and functions may be easier to understand than BPMN parsing and engine concepts. SpiffWorkflow earns its extra model complexity when diagrams, pools and lanes, events, multi-instance behavior, sub-workflows, or domain decisions justify that structure. The choice should therefore turn on the required process semantics, not on the breadth of a feature checklist. A hosted platform reduces infrastructure ownership but introduces service integration and vendor constraints. SpiffWorkflow offers direct Python control and limited runtime dependencies, but its users own more of the application boundary. The README also keeps Python workflows and internal JSON definitions available, which can be preferable for narrowly scoped logic even though it reduces the immediate case for BPMN. ## Conclusion SpiffWorkflow fits Python teams that need BPMN and DMN processing without adopting a Java-centered stack. It is a poor fit for developers who need a self-contained quick-start or expect the README alone to explain process construction and execution. Before adoption, verify that the external documentation covers the exact BPMN constructs and persistence model required by the application, then build and test the package from the repository before integrating it. ## FAQ ### How do I install SpiffWorkflow? The README gives `pip install spiffworkflow` as the installation command. The package metadata requires Python 3.10 or later. ### Does SpiffWorkflow support BPMN and DMN? Yes. The README documents BPMN parsing and execution plus a baseline DMN implementation integrated with the Python execution engine. It does not claim complete DMN feature parity. ### Can I define a SpiffWorkflow workflow without BPMN? Yes. The project retains support for workflows built directly in Python and workflows based on an internal JSON data structure. ### How do I run the SpiffWorkflow tests? After `pip install -e .[dev]`, run `make tests`. The Makefile invokes Python's `unittest` discovery against the repository's test tree. ## Sources - [Issues](https://github.com/sartography/SpiffWorkflow/issues) - [License: LGPL-3.0](https://github.com/sartography/SpiffWorkflow/blob/main/LICENSE) - [README](https://github.com/sartography/SpiffWorkflow/blob/main/README.md) - [Releases](https://github.com/sartography/SpiffWorkflow/releases) - [sartography/SpiffWorkflow on GitHub](https://github.com/sartography/SpiffWorkflow) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sartography-spiffworkflow