Installation

Prerequisites

CPython

WinCC OA does not ship a Python runtime. Install CPython yourself.

Which CPython version is used follows a fixed pattern:

Linux: the system Python of the distribution.
Windows: the CPython version that is current when the WinCC OA version is released, installed from python.org.

The exact version per operating system is listed in the WinCC OA online help, chapter Software Requirements > Python.


Version	Meaning
Released version	Tested by ETM and officially supported. Use this version.
Minimum version	Same as the released version. The extension refuses to load into an older CPython.
Newer version	The extension uses the stable ABI of CPython, so it also loads into newer CPython versions. Newer versions are not tested. Using them is at your own risk. Exception: on Debian 12 the extension is built for CPython 3.11 without the stable ABI and loads only with exactly this version.

Some Linux distributions support installing a newer CPython alongside the system Python. If you do so, follow the instructions of your distribution. On Debian 12 this does not work: the extension loads only with CPython 3.11, see Troubleshooting.

WinCC OA looks for the python executable in the bin/ directories of the project, its subprojects and the installation, and finally in the system PATH. To pin a specific interpreter for one project, place the executable — or a link to it — in <project>/bin/.

WinCC OA

The Python packages and the native extension are delivered with WinCC OA and form one unit with the installation. They are not versioned independently, so an installation of one version cannot be combined with API packages from another version. Whenever you update WinCC OA, the Python API is updated as well.

Not every WinCC OA version contains the Python API. Consult the release notes before you plan to use it on an existing installation.

Which parts of the Python support you need depends on the machine, as described in the next section.

Installation Components

Python support is split into two setup components with different purposes.


Component	Purpose	Install on
`PythonEnv`	Runtime — everything needed to execute a Python manager	Every machine that runs a Python manager
`APIPython`	Developer SDK — wheels, examples and API documentation	Engineering stations and developer workstations

PythonEnv is the only component required to run a Python manager. APIPython adds nothing to the runtime. It exists to support writing and testing Python code.

PythonEnv — Runtime


Content	Target directory
Native extension `_etm_wccoa_manager_scripting`	`<WINCCOA_ROOT>/bin/`
Packages `etm.wccoa`, `etm.wccoa.manager`, …	`<WINCCOA_ROOT>/python/libs/etm/`

The packages are installed unpacked rather than as wheels, so no pip install is needed. When PMON starts a Python manager, it sets PYTHONPATH and WCCOA_BIN_DIRS so that the packages and the native extension are found automatically.

APIPython — Developer SDK


Content	Target directory
Wheels `etm_wccoa-.whl`, `etm_wccoa_manager-.whl`, …	`<WINCCOA_ROOT>/api.python/packages/`
Example scripts	`<WINCCOA_ROOT>/api.python/examples/`
API documentation, HTML and Markdown	`<WINCCOA_ROOT>/api.python/docs/`

The wheels are meant to be installed in a virtual environment with pip. They provide code completion, type checking and offline unit tests in the IDE. See Development Environment.

Windows

WinCC OA is installed using a setup program. Components are grouped into workloads, and each workload preselects the components typical for its use case.


Workload	`PythonEnv`	`APIPython`
Minimal Server	—	—
Runtime Server	yes	—
Development Server	yes	yes
All Components	yes	yes
Desktop UI	—	—

Choose Runtime Server for a machine that only executes Python managers, and Development Server for a machine on which Python code is written.

Regardless of the workload, both components can be selected individually. In the setup, they appear as:


Component	Name in the setup
`PythonEnv`	Environment for Python
`APIPython`	API Python

To add a component to an existing installation, run the setup again and choose the modify option.

Linux

WinCC OA is delivered as operating-system-specific package files. Install them with the package manager of your distribution. There are no workloads on Linux — every component is a separate package and is selected individually.


Component	Package file
`PythonEnv`	`winccoa-<version>-PythonEnv-<distribution>.<architecture>.deb` / `.rpm`
`APIPython`	`winccoa-<version>-APIPython-<distribution>.<architecture>.deb` / `.rpm`

Both packages depend on other WinCC OA packages of the same version:


Component	Depends on
`PythonEnv`	the WinCC OA base server package and `python3`
`APIPython`	the WinCC OA base package

Install the base packages first, or pass all package files to the package manager in one call so that it can resolve the dependencies.

Debian

sudo apt install ./winccoa-<version>-PythonEnv-<distribution>.<architecture>.deb

Red Hat Enterprise Linux

sudo dnf install ./winccoa-<version>-PythonEnv-<distribution>.<architecture>.rpm

The same commands apply to APIPython on a developer workstation.

Directory Layout

Installation Directory

<WINCCOA_ROOT>/
├── bin/
│   └── _etm_wccoa_manager_scripting…      native extension            (PythonEnv)
├── python/
│   └── libs/
│       └── etm/
│           └── wccoa/
│               ├── datatypes/             data type mapping           (PythonEnv)
│               ├── exceptions/            error types                 (PythonEnv)
│               ├── services/                                          (PythonEnv)
│               ├── manager/               Manager and scripting API   (PythonEnv)
│               └── msa/                   Manager Service API         (PythonEnv)
└── api.python/
    ├── packages/                          wheels                      (APIPython)
    ├── examples/                          example scripts             (APIPython)
    └── docs/
        ├── html/                          API documentation           (APIPython)
        └── markdown/                                                  (APIPython)

etm.wccoa is a namespace package. All packages of the runtime component share the same directory tree under python/libs/etm/. The directory python/libs/ is the import root: it is what PMON adds to PYTHONPATH, together with bin/ for the native extension.

The file name of the native extension depends on the platform and on the CPython version for which it was built:


Platform	File name
Windows	`_etm_wccoa_manager_scripting.abi3.pyd`
Linux, CPython 3.12 or later	`_etm_wccoa_manager_scripting.abi3.so`
Linux, CPython 3.11	`_etm_wccoa_manager_scripting.cpython-311-<architecture>-linux-gnu.so`

Project Directory

<project>/
├── bin/                  optional: project-specific python executable
├── config/
│   └── progs             manager entries written by the Console
├── log/                  PVSS_II.log and the manager-specific log files
└── python/               your Python scripts

Scripts are resolved in the python/ directory of the project first, then in those of its subprojects, and finally in the installation. This allows a subproject to ship scripts that every project using it can start.