How-to
Run Python scripts from a soft PLC runtime on Linux
Short answer
Call the script by giving the runtime's process-execution function the full string python3 /path/to/script.py, not a shebang. Put the process-execution permission in CODESYSControl_Usr.cfg, the user configuration file that survives runtime updates since release 4.13.0.0, because the main config file is overwritten. Prove the script in the Linux shell first, and containerize Python when the controller has no package feed.
On this page
- How do I run a Python script from a soft PLC runtime on Linux?
- Why does the runtime refuse to start an external command?
- Which configuration file survives a runtime update?
- Should I call the script by shebang or by name?
- How do I prove the script runs before it goes into PLC logic?
- Do I install Python natively or run it in a container?
- Where should the script's output and errors go?
- What changes on a small controller instead of a full PC?
- Questions asked
Running a Python script from a soft PLC runtime on Linux is a configuration problem before it is a programming problem. The runtime has to be allowed to start external processes, that permission has to sit in the file a runtime update does not delete, and the call has to reach the interpreter in a form that cannot break. Get those three right and the same call survives years of runtime upgrades; get the second one wrong and the script dies silently at the next update. This article works on CODESYS Control for Linux SL, documented as a soft PLC under IEC 61131-3, the standard that defines PLC programming languages; the same moves apply on other Linux soft runtimes that expose a process-execution library, with their own file names.
How do I run a Python script from a soft PLC runtime on Linux? #
Write the script, prove it from the Linux shell, put the process-execution permission in CODESYSControl_Usr.cfg, restart the runtime, and call the interpreter by name with the full script path from PLC logic.
CODESYS Control for Linux SL turns a PC-based industrial controller into a soft PLC under IEC 61131-3, and like most soft runtimes it starts external programs only once its configuration allows it. The whole procedure, start to finish:
- Confirm the interpreter exists on the controller:
python3 --versionin the controller's Linux shell prints the version. - Write the script into a directory the runtime can read — this article uses
/opt/plc-scripts/as its illustrative location — and run it once from the shell. - Add the process-execution permission to
/etc/codesyscontrol/CODESYSControl_Usr.cfg, the user configuration file. - Restart the runtime so it re-reads the configuration; if the controller starts it through systemd, apply the service-level override first.
- From the PLC program, hand the command-execution function one string:
python3 /opt/plc-scripts/heartbeat.py. - Read the exit code and the output on the runtime side, then put the call into production logic.
Steps 3 and 4 cause most of the failed first attempts, so each gets its own section below.
Why does the runtime refuse to start an external command? #
The runtime ships with external process execution disabled, so the command-execution function fails until the runtime configuration allows it — and on systemd setups the service unit can add restrictions of its own that a config entry alone does not lift.
There are two layers, and a failure at either looks identical from the PLC: the command-execution function — SysProcess Execute Command in the runtime's process-handling library — reports that it cannot run the command.
The configuration layer carries a permission entry for the process-execution component. Add the entry that allows external commands in the exact spelling your installed runtime's documentation and its shipped example configuration show; the key differs between runtime versions, so match it to the version running on the controller, not to an older example.
The service layer: on distributions that start the runtime through systemd, create or edit a systemd override with sudo systemctl edit codesyscontrol, reload systemd, and restart the service. Unit-level restrictions do not appear in the runtime's own configuration and cannot be lifted from it.
One safety rule: allowing process execution means the runtime can start arbitrary programs, so enable it only on controllers that need the capability and keep those controllers unreachable from untrusted networks.
Which configuration file survives a runtime update? #
Since release 4.13.0.0 the path changed: put your settings in /etc/codesyscontrol/CODESYSControl_Usr.cfg, because a runtime update overwrites CODESYSControl.cfg and leaves the Usr file untouched — a permission added to the main file disappears at the next update.
An update rewrites the main configuration file with the new version's defaults, and everything you added there — the process-execution permission included — is gone. The symptom is distinctive: a script that ran for months fails after an update with the same command-execution error you saw before any configuration. The user file exists precisely to prevent this; the updater leaves it alone.
If a controller still carries the permission in the main file, move the entry into the user file at the next maintenance window, restart the runtime, and confirm one call from PLC logic. Runtimes older than 4.13.0.0 predate this file, which is a second reason to bring them forward before you depend on external calls at all.
Should I call the script by shebang or by name? #
Always call the interpreter by name — python3 /opt/plc-scripts/heartbeat.py — because an explicit interpreter path removes both failure modes of shebang execution: a missing executable bit and an interpreter line pointing at a path the controller does not have.
A shebang call (./heartbeat.py) needs the executable bit set on the file and a first line naming an interpreter path that exists on that controller. Both hold on your desk and either breaks on the target after a file copy, a permission change or an image rebuild. The explicit call depends on neither. It also makes the interpreter choice visible in the PLC program and in logs, and it carries arguments the same way a shell does: python3 /opt/plc-scripts/read.py --station 4 passes the flag unchanged.
How do I prove the script runs before it goes into PLC logic? #
Run the exact command string from the Linux shell and require three results before it goes anywhere near the PLC: exit code 0, the output you expect, and a runtime comfortably inside the delay your process tolerates.
Run the exact string from the shell. The paths and output below are this article's illustrative example, not shipped files:
$ python3 /opt/plc-scripts/heartbeat.py
ok 2025-05-13T08:00:01Z
$ echo $?
0
If the runtime service runs under its own user account, repeat the test under that account as well — a script readable by your login can be unreadable by the service account, and the PLC side will fail where your desk passed.
On the PLC side, declare one variable of type STRING, initially empty, fill it with python3 /opt/plc-scripts/heartbeat.py before the call, and pass it to SysProcess Execute Command. Make the script call sys.exit(1) on its own failure paths, so a partial result can never masquerade as success.
Do I install Python natively or run it in a container? #
Install python3 natively from the distribution repository on an industrial PC with a standard distro; containerize when the controller's image has no package feed or you need interpreter and dependency versions pinned against OS updates.
Native: the distro package manager installs python3 and its security updates maintain the interpreter afterwards; project libraries live in a virtual environment per application. Container: an image pins the interpreter and every library, versions become an image tag, and an OS or runtime update cannot move anything underneath the script.
Cross-compiling Python with the vendor SDK for a controller target is possible, but you then rebuild for every library bump — choose that road only when neither a package feed nor a container engine exists. Containerized workloads beside a controller runtime are routine; the same mechanism is described in deploying Edge Data Store in Docker on a controller PC.
Decision: full PC with a standard distro — native. Strict dependency versions, or an OS image you do not control — container.
Where should the script's output and errors go? #
Let the script print to stdout and read it through the execution function; if you add a file log, size it first: one 80-byte line per minute is 115 kB a day and about 42 MB a year, so cap the file.
Read stderr as well as stdout, or the first failed run hides its traceback from you. Keep the script non-interactive — a script that waits on input never returns, and the call hangs until someone kills it.
Worked example, illustrative: the heartbeat script appends one line of about 80 bytes each time the PLC calls it, once a minute.
- Per day: 80 B × 1,440 calls = 115,200 B ≈ 115 kB
- Annually: 115,200 B × 365 = 42,048,000 B ≈ 42 MB
A rotation of four files at 5 MB caps storage at 20 MB and keeps 20,000,000 ÷ 115,200 ≈ 173 days of history. Decision: print to stdout by default, because the execution function hands it to you and it cannot grow; add a size-capped rotating file only when you need history the runtime does not keep.
What changes on a small controller instead of a full PC? #
On a compact controller the native install exists only if the image ships a package feed for its architecture; when there is no feed, the decision is made for you — the script belongs on a PC, not on a hand-built interpreter.
A full PC with a standard distribution has a package feed, so the native install is one command and nothing else is needed. Many compact controllers — the box-style PLC-class devices — run a minimal or read-only image with no feed for their architecture, and there the native route may not exist at all. One python3 --version on the target answers the question in ten seconds, so run it before you design the dependency set.
Decision, case by case: a PC with a standard distro takes the native install; a compact controller with a feed takes the native install with the shortest dependency list you can manage; a compact controller with no feed and no container engine cannot host the script, and the work belongs on a separate edge computer that exchanges data with the controller over MQTT or files — the split described in running Python and Node-RED beside PLC code on an edge PC. Building a hand-rolled interpreter for a small target is the last resort, taken only when the vendor SDK is the sole path and the maintenance burden is accepted.
Questions asked
Does calling Python disturb the PLC task cycle?
The script runs as its own Linux process, scheduled by the operating system separately from the runtime's real-time task, so the logic keeps its cycle while the script runs. What the script delays is the data it hands back. Keep scripts short, never block the PLC task waiting on a slow script, and put long work on a separate edge computer; CODESYS Control for Linux SL is documented with soft real-time properties, not hard ones.
Can I pass arguments and get a result back from the script?
Yes. Build the command string with the arguments appended exactly as a shell would receive them, for example python3 /opt/plc-scripts/read.py 2025-05-13. How the exit code reaches the PLC depends on the execution function's outputs, so verify that in the library documentation of your installed runtime; the robust pattern is to have the script print its result or write it to a file, and read it from there. One string in, one exit code and one output channel out.
How do I find every controller where external execution is enabled?
List each controller's user configuration file, CODESYSControl_Usr.cfg under /etc/codesyscontrol on the Linux SL runtime, and record the machines where the process-execution permission appears. Any controller with the permission but no external call in its program should lose the entry, because the permission lets the runtime start arbitrary programs. Re-run the list after each runtime update campaign: updates rewrite the main config file, and the machines you touched are the ones to re-verify.
Which Python version should the script target?
On a native install, target the major version the distribution ships, and expect security updates to move only the patch number. Re-run the shell test after any major OS upgrade, because that is what replaces the interpreter. In a container the image tag pins the version, so it changes only when you change it, which is the main reason to prefer a container for scripts with strict dependency versions.