PyFlowRED

A port of Node-RED 5.0.7 to Python.

The same editor, the same flow file, the same node set, the same HTTP admin API — with a Python runtime and nodes written in Python.

What "port" means here

The editor is not a reimplementation. It is Node-RED's own editor, talking to a Python implementation of the API it expects. Flows exported from Node-RED import into PyFlowRED and back again: the flow file is the same JSON, and the credentials file uses the same encryption.

See docs/porting.md for the full correspondence.

Where it deliberately differs

Two things cannot be carried over one-to-one, because they are the JavaScript runtime:

1. The Function node runs Python. The same three tabs (On Start, On Message, On Stop), the same node / flow / env objects, the same send and done semantics — but the body is Python:

   msg["payload"] = msg["payload"] * 2
   return msg
   

   The body is compiled into an async def, so await works directly. global is a Python keyword, so the global context object is global_.

2. Packages come from PyPI. The Function node's Setup tab and the palette manager install Python distributions. A PyFlowRED node package is an ordinary distribution that advertises a pyflowred.nodes entry point.

Installing

pip install pyflowred     # or: uv pip install pyflowred
pyflowred

One name throughout: the distribution on PyPI, the command, the import package, the PYFLOWRED_* settings and the editor are all pyflowred. (pyred was already taken on PyPI, which is where the name came from; up to 0.1.0 the import package and command were still pyred, and 0.2.0 renamed them to match.)

The wheel carries the built editor, so this needs Python and nothing else — no Node, no build step. The editor is then at http://127.0.0.1:1880/.

In a container

Two images, same application. Dockerfile installs the released package with uv and carries no build tooling; Dockerfile.source builds this checkout in three stages, Node included.

docker build -t pyflowred:0.3.0 .                        # released
docker build -f Dockerfile.source -t pyflowred:source .  # this checkout
docker run -d -p 1880:1880 -v pyflowred-data:/data pyflowred:0.3.0

Your own CA is a build argument or a mount, and reaches every library in the runtime. See docker/README.md.

Building it

Node.js is needed once, to build the editor. It is never needed at runtime.

npm install          # editor build dependencies
npm run build        # builds src/pyflowred/editor_client/public
uv build --wheel     # ~10 MB, py3-none-any

That build output is a git-ignored artifact, so the wheel has to pull it back in deliberately (tool.hatch.build.targets.wheel.artifacts). A build hook refuses to produce a wheel when the editor has not been built, because the failure mode otherwise is a package that installs, starts, and serves a blank page. The editor source is excluded from the wheel and kept in the sdist, where it can be rebuilt.

Working on it

npm install && npm run build
uv venv --python 3.13
uv pip install -e ".[dev]"
.venv/bin/pyflowred

Without adminAuth, anyone who can reach the editor can run arbitrary Python as the user running the process. See docs/operations.md.

Writing a node

def register(RED):
    class LowerCaseNode(RED.Node):
        def __init__(self, config):
            super().__init__(config)
            self.on("input", self._on_input)

        def _on_input(self, msg, send, done):
            msg["payload"] = msg["payload"].lower()
            send(msg)
            done()

    RED.nodes.register_type("lower-case", LowerCaseNode)

with the matching .html next to it, exactly as in Node-RED. A complete example package is in examples/pyflowred-node-lowercase; the details are in docs/writing-nodes.md.

Layout

src/pyflowred/
  util/            property expressions, JSONata, mustache, cloning, logging, i18n
  runtime/         flow engine, node registry, context, credentials, storage
  registry/        node discovery, loading, palette installation
  api/             HTTP admin API, editor routes, comms WebSocket (Starlette)
  metrics/         the Prometheus registry, runtime instrumentation, endpoint
  streaming/       keyed state on RocksDB, windows, aggregate functions
  nodes/core/      the core node set: Python implementations + Node-RED dialogs
  editor_client/   the Node-RED editor, vendored and built
tools/
  editor-build/    the Node-RED editor build pipeline, re-pointed at this repo
  devserver.sh     start/stop a throwaway instance
  uicheck.py       load the editor in a real browser and report on it
  uiflow.py        deploy and run a flow through the editor, in a real browser
  uiprojects.py    commit a deploy through the project UI, in a real browser
  uigcs.py         check the Cloud Storage dialogs are typed inputs, in a browser
  uistream.py      check the stream processing dialogs, in a browser
  e2eflows.py      the end-to-end integration test: 18 tabs, 157 assertions
  coverage.py      what a run reached: node types and dialog choices
  e2e/             the MQTT broker and Kafka the test talks to
  e2eflows.py      the end-to-end integration test: 12 tabs, 45 assertions
  coverage.py      how much of the node set a run actually reached
  e2e/             the MQTT broker and Kafka that test talks to
  benchflows.py    seven benchmark flows, 82 nodes across 33 node types
  loadtest.py      drive them and sample the runtime's CPU, RSS and fds
  rawbaseline.py   a bare Starlette endpoint, to measure the runtime against
Dockerfile         the released package, installed with uv
Dockerfile.source  this checkout, editor and all
docker/            entrypoint, compose, CA drop-in
examples/          an example node package
docs/              porting notes, node authoring, operations, benchmarks
tests/             the test suite, including a browser test of the editor

Tests

.venv/bin/python -m pytest tests

docs/test-coverage.md is the standing record of what is tested, how, and what is not - including the 24% of end-to-end assertions that so far only check that something arrived rather than what it was.

The suite covers every node group against real sockets (including an in-process MQTT broker), the runtime (subflows, groups, context, credentials, deploy types), the admin API, projects against a real git binary, and — when Playwright is available — the actual editor in a headless browser: import a flow, press Deploy, open the Function node, click Inject, read the debug sidebar.

Licence

Apache-2.0, as Node-RED is. The vendored editor and node dialogs keep their original copyright headers.