TensorFlow-Unreal 2.0: a Python process that never touches the game thread

What the 2.0 rewrite changed and why it matters

TensorFlow-Unreal is a plugin that brings TensorFlow and Keras into Unreal Engine 5.8, usable from Blueprints and from C++. You write the model in Python, the plugin runs it, trains it, feeds it inputs such as render targets and audio, and returns results and events back into Unreal.

Version 2.0 is described as a full rewrite, and the list of what changed is the interesting part.

Python now runs out of process, in an embedded interpreter with a per-project virtual environment, through the PythonCLI plugin on top of the CLISystem plugin. The consequence, stated plainly, is that a crash in TensorFlow never takes the editor down, and the GIL never touches the game thread.

The second point deserves unpacking because it is the one that determines whether this design is usable in a shipping game. A global interpreter lock means only one Python thread runs at a time, and if Python ran on the game thread, any long TensorFlow operation would stall the frame. Moving Python into a separate process with its own interpreter means the engine keeps rendering while a model runs, and a segfault in a native TensorFlow op kills the Python process rather than the editor.

Three things are gone in 2.0: MachineLearningRemote, socket.io and UnrealEnginePython. The UnrealEnginePython removal is notable, and dropping it means the plugin now depends on a different Python stack entirely.

What stayed the same matters too. The Python API is unchanged, so existing TFPluginAPI scripts keep working, and the documentation includes a migration section for people coming from 1.x.

Setup is three plugins and one background download

The install is a three-step process, and step two is the one that takes time.

First you put three plugins into your project's Plugins directory: TensorFlow-Unreal itself, PythonCLI-Unreal, and CLISystem-Unreal. Release archives include all three along with the Python interpreter, while from git you fetch the interpreter with PythonCLI's Tools/FetchRuntime.ps1, or fetch_runtime.sh.

Then you start the editor. In the background, PythonCLI creates Intermediate/PythonCLI/venv and installs the TensorFlow profile into it. The download is about 350 MB, once. Later starts skip the setup, and a rebuilt virtual environment comes from uv's cache in seconds.

The third step is the one that connects the plugin to your work. You add a TensorFlow component to an actor and set Script Params > Script to your script, for example my_model for Content/Scripts/my_model.py, or to a bundled example such as examples/mnist_keras_cnn.

Two practical notes from the setup section. On long paths, keep the project path short or enable long paths on Windows, because TensorFlow's files are deep and the Windows path limit is a genuine failure mode here. And the log level is controlled through the profile's TensorFlow Log Level, which sets the TF_CPP_MIN_LOG_LEVEL environment variable, which is how you quiet TensorFlow's own console output inside the editor.

The status line is worth repeating: version 2.0.0, tested on Win64 in the editor and in packaged builds, and on Linux x86_64 in packaged builds.

Four environment profiles and the Windows GPU gap

The profile system is where the plugin's real trade-offs are, and it exists because TensorFlow's platform support is uneven.

The default is TensorFlow CPU, installing tensorflow-cpu 2.21, and it works on Windows and Linux. The reason it is the default is stated in the table: Windows has had no native TensorFlow GPU build since 2.10.

That single fact shapes the rest of the choices. The TensorFlow CUDA profile installs tensorflow[and-cuda] 2.21, which is for Linux with an NVIDIA GPU and pulls in a few GB of CUDA wheels. The third profile is Keras on PyTorch, installing keras 3 with a torch CUDA build, and its stated use is GPU on Windows, running Keras 3 on the torch backend with KERAS_BACKEND=torch set. The fourth profile is None, which installs nothing, for the case where you list your own packages.

The workaround for your own packages is either Project Settings > Plugins > Python CLI > Requirements, or a Content/Scripts/requirements.txt file.

This profile design is an admission that the plugin cannot present a single machine learning stack. A team shipping a Windows game with GPU inference has to go through PyTorch and Keras rather than TensorFlow proper, and the model code then has to be written to run on either backend. That is a real constraint on the design of the model, not just on the build.

The Python API is a set of hooks, and the concurrency model is the surprise

The Python side is a class with lifecycle hooks, and the shape of the example makes the model of use clear.

import unreal_bridge as ue
from unreal_bridge.ml import TFPluginAPI   # or MLPluginAPI: the same class, snake_case hooks

class Classifier(TFPluginAPI):
    def on_setup(self):                    # once, when the script starts: build or load the model
        import keras
        self.model = keras.saving.load_model(ue.content_path("Models", "mnist.keras"))

    def on_tensor_input(self, image):      # Send Tensor Input / Texture / Render Target: a numpy array
        scores = self.model(image[None], training=False)
        return {"prediction": int(scores.numpy().argmax())}

The full hook list is on_setup, on_json_input, on_float_array_input, on_tensor_input, on_begin_training, on_stop_training, on_save_model and on_load_model, and the camelCase forms from 1.x still work, so onJsonInput and onBeginTraining continue to fire. Any other method can be called from Unreal through Call Custom Function. Stopping is handled by self.should_stop, which turns true on Stop Training, a script stop or reload, and EndPlay, so a long fit call can be interrupted. Events go out through self.call_event(name, data) to On Custom Event and self.report_progress(data) to On Training Progress.

The concurrency note is the part that changes how you write the code: inputs are answered while training runs. Everything else for a script runs in order, on that script's own thread. So a model can keep serving inference calls during a training session, and a training callback can call ue.keras.StopOnRequest(self) to end the fit, with ProgressEvents(self) reporting back to Unreal.

The rest of the unreal_bridge module, with ue.log, ue.emit and the @ue.on_stream decorator, is documented in the PythonCLI README rather than here.

Packaging is where the 1.2 GB shows up

Packaged games on Win64 and Linux take the interpreter, the scripts, and by default the installed packages with them. PythonCLI installs the environment's packages for the target platform while packaging, which is a detail that solves a real problem: a Linux build packaged on Windows gets Linux wheels rather than Windows ones.

The size cost is stated precisely. The tensorflow-cpu profile adds about 1.2 GB to a Linux build and 1.3 GB to a Win64 build. That is the price of shipping a TensorFlow runtime to end users, and it is not a rounding error against a typical game download size.

There is an escape hatch, and it is the setting to look at first if the size is a problem. Set Project Settings > Plugins > Python CLI > Packaged Env Mode to Install On First Run, and the game installs the environment on its first launch instead. The trade is that the first run now depends on a download, so the user experience at startup changes and the machine needs network access.

The other thing to know about the Blueprint API is where the TensorFlow component actually runs. It is a Python ML component, and it runs in PythonCLI's shared Python process by default, which is the same out-of-process interpreter described earlier. Send Json Input and Send String Input call on_json_input or a named function and the result arrives in On Input Results. Send Tensor Input passes a tensor, built with Make Tensor From Floats or Texture To Tensor. Send Texture Input and Send Render Target Input pass an image to on_tensor_input as a float32 tensor in H, W, C order, with grayscale, RGB or RGBA channels, and the plugin handles resize, invert and normalisation.

A PyTorch alternative exists, and the documentation points at it

The readme has a section titled PyTorch Alternative, and its reasoning is worth taking at face value because it is the author of the TensorFlow plugin saying so.

The advice is that if you find TensorFlow GPU support on Windows lacking, or if you would like to use a more modern Python ML library with Unreal, you should consider the PyTorch-Unreal plugin instead.

That is a fairly damning summary of TensorFlow on Windows, and it is consistent with the environment profile table, where the default profile is CPU-only and the Windows GPU route goes through Keras 3 on the torch backend rather than through TensorFlow itself. If you have a choice and your inference needs a GPU on Windows, the documentation is pointing you at a different plugin rather than asking you to work around the limitation.

The version history also tells you something about the shape of the project. The 2.0.0 release is for UE 5.8, dated 2026-10-13, and before it sit v1.6.0beta for UE 5.3 from 2024-08-30 and v1.5.0beta for UE 5.3 from 2023-11-01. So the 1.x line was itself a set of beta releases tracking Unreal 5.3, and 2.0 is the first stable-numbered release. The gap between the last 1.x beta and 2.0.0 is about two years, which is a long time for a plugin to sit in beta.

The repository is not archived, the last push was on 2026-10-13, and the licence is a custom one that GitHub cannot classify, with the terms in the LICENSE file at the repository root.

Editorial conclusion

TensorFlow-Unreal is the right pick for a team shipping machine learning behaviour inside an Unreal project, especially one that trains or runs models at runtime, because the 2.0 rewrite isolates Python failures from the editor and keeps the game thread free of the GIL; it is the wrong pick for a project that only needs to export assets or bake a model offline, since the packaged build grows by roughly 1.3 GB, and before you commit you should decide between the bundled tensorflow-cpu profile and installing the environment on first run, because that choice determines whether your build artefacts stay small.

Frequently asked questions

Official sources

1. getnamo/TensorFlow-Unreal on GitHub
2. Issues
3. README
4. Releases