QtNodes (paceholder/nodeeditor): a Qt graph model for dataflow editors

What problem QtNodes solves, and who it is aimed at

Building a node editor from scratch means writing hit testing, port geometry, connection routing, selection, undo and serialization before you write a single line of your actual application logic. QtNodes exists to absorb that work. The README describes it as "a general-purpose Qt-based library aimed at developing Node Editors for various applications", usable either for plain graph visualization and editing or extended toward the dataflow paradigm.

The intended reader is a C++ developer already working in Qt. The dependencies section lists Qt >5.15, CMake 3.11 and Catch2, so the project assumes a desktop Qt toolchain and a CMake build. If you are looking for an application you can install and draw graphs in, this is not that. It is a library, and the repository ships examples rather than a product.

The scope is deliberately wider than dataflow. The README states the library "is now designed to be general-purpose graph visualization and modification tool, without specialization on only data propagation." So it fits a state machine editor, a shader graph, a dependency viewer or a pipeline designer equally well, provided the host application is Qt-based.

The model-view split and how data actually moves

The architecture is Model-View. The entire graph structure lives in a class you derive from AbstractGraphModel, and that class can hold nodes and connections in whatever data representation you like. The README is explicit that the underlying structures "could be of any arbitrary type or representation", which is the main reason to choose this library over a fixed graph container.

An AbstractGraphModel instance does not have to be attached to a QGraphicsScene or QGraphicsView. The README calls this the "headless" modus operandi. That matters for two cases: batch processing a graph without a UI, and unit testing graph logic without spinning up a widget. The bundled test suite covers core model operations, signal emission from AbstractGraphModel, JSON save/load, and undo integration, which is consistent with the model being usable on its own.

Dataflow is a separate layer. DataFlowGraphModel is an extended model class that lets you register processing algorithms as nodes, and it uses Qt signals and slots to push data through the graph. The trigger rule is stated plainly: a node's algorithm runs when any new input data arrives, the result goes to the output connections, and each change in a source node propagates through all connections. That is eager push propagation, not lazy pull evaluation. If your algorithms are expensive and most outputs are never consumed, this design will run work you did not need.

Installing QtNodes and running the calculator example

There is no package manager entry in the README. You clone the repository and build it with CMake. The README gives the Linux path and a flag to choose the Qt major version, since USE_QT6 defaults to on and must be set to off for Qt5.

git clone [email protected]:paceholder/nodeeditor.git
cd nodeeditor
mkdir build
cd build
cmake .. -DUSE_QT6=off
make -j && make install

If Catch2 is not installed on the machine, the README notes that testing can be disabled with -DBUILD_TESTING=OFF during CMake configuration. Static linking is available through -DBUILD_SHARED_LIBS=off. For vcpkg users, the README says to add the toolchain file flag at configuration time:

-DCMAKE_TOOLCHAIN_FILE=<vcpkg_dir>/scripts/buildsystems/scripts/buildsystems/vcpkg.cmake

Qt Creator users can open CMakeLists.txt as a project, then run Build -> Run CMake, Build -> Build All, and the Run button. After the build, the examples directory is the place to start. The README lists examples/calculator/, examples/dynamic_ports/, examples/simple_graph_model/ and others. For a first real use, simple_graph_model is the smallest demonstration of the model layer, while calculator shows the dataflow layer where node algorithms fire on new input. The README does not give a command for launching an individual example, so check examples/CMakeLists.txt for the target names in your build tree.

The 3.0 break and what it costs to upgrade

The README carries a warning that "Many classes were changed in the version 3.0." If you have a large project on 2.x.x, the advice is to read the documentation and the examples before checking out new code. That is a real migration, not a flag flip. The branch layout reflects it: v2 and v3 hold the 2.x.x and 3.x lines, and master is described as the latest dev state. Building against master means building against whatever is in development.

There are no releases in the repository information, so consumers pin a branch or a commit. The README's own citation block pins a commit hash, which is a reasonable hint about how the project expects to be consumed. There is no documented rollback procedure and no versioned changelog in the README beyond the 3.0 warning, so plan to read the Read the Docs site before moving a production codebase across the major version boundary.

Maintenance is a single maintainer working in free time, stated directly in the contribution section, with an explicit request to ping if there is no response for too long. The last push to the repository was on 2026-07-31. Budget accordingly: a library like this is a dependency you may need to patch yourself.

Where QtNodes is the wrong tool

The library gives you no editor application. There is no installer, no binary release, and no configuration format for end users. Everything the user sees is code you write on top of AbstractGraphModel and the Qt graphics classes. If your requirement is to hand a designer a node tool next week, this adds a development project to your schedule.

Eager propagation is the second constraint. Every new input runs the node algorithm and pushes results downstream immediately. A graph with heavy nodes and a large fan-out will recompute more than a pull-based evaluator would. The README does not describe a dirty-flag or deferred evaluation mode, so if you need that, you build it into your model class.

Language and toolkit lock-in is the third. The project is C++ and Qt. The README lists Python wrapping using PySide and a QML frontend under Help Needed, meaning neither exists. A team writing a Python tool or a web UI cannot use this library today. Headless mode softens the constraint for server-side graph processing, but the build still requires Qt.

How it compares to immediate-mode node editors

The most common alternative in this space is an immediate-mode node editor built on Dear ImGui, where the graph is redrawn and hit-tested every frame and the editor state lives in plain structs you own. The difference is structural, not cosmetic. ImGui-style editors draw through a rendering backend and suit applications already using an immediate-mode UI, often in game engines or tools embedded in a 3D viewport. QtNodes instead plugs into Qt's retained-mode QGraphicsScene and QGraphicsView, so it inherits Qt's item system, widget embedding and event model.

That inheritance is the trade. You get embedded Qt widgets inside nodes, JSON-based interface styles, undo/redo and duplication with CTRL+D, vertical and horizontal layouts, and datatype-aware connections, all listed as current v3 features. You also take on Qt as a dependency and the model-view indirection, where every graph mutation goes through your AbstractGraphModel subclass. For a Qt desktop application, that indirection is a feature: the graph model is testable without a scene. For a project that has no Qt, it is the reason not to look further.

Licence, dependencies and what to verify before adopting

QtNodes is BSD-3-Clause. That is a permissive licence, and the repository ships LICENSE.rst at the top level. The practical implication is that you can use it in closed-source products provided you keep the copyright notice and disclaimer, but this is not legal advice and your counsel should read the actual file. Note that the licence covers QtNodes, not Qt itself, and Qt licensing is a separate decision.

Dependencies are Qt >5.15, CMake 3.11 and Catch2, with Catch2 only needed for the test suite. The README lists tested platforms as Linux x64 with gcc, OSX with Apple Clang, and Windows with MSVC, on Qt 5.15.2 and Qt 6.3.0. Those are the configurations the CI badge covers. Newer Qt versions are not listed, so verify your specific Qt build before planning around it.

For a first evaluation, clone the repository, build with -DBUILD_TESTING=OFF if Catch2 is not present, and read examples/simple_graph_model/ alongside the Read the Docs pages. If the model interface fits your data structures, the rest of the library is mostly a matter of wiring the view.

Editorial conclusion

Adopt QtNodes if you are building a C++/Qt application and want the graph model, ports, connections and scene management handled for you while you supply the domain logic. Do not adopt it if you need a ready-made editor binary, a Python or C# binding, or a non-Qt UI toolkit; the README lists Python wrapping via PySide and a QML frontend as help still wanted. Before committing, check out the v3 branch rather than master, confirm your Qt version against the USE_QT6 flag, and read the 3.0 migration warning if you have existing 2.x code.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. paceholder/nodeeditor on GitHub
4. README