Introduction and Configuration

Embedded Python allows you to use Python as a native option for programming InterSystems IRIS applications. If you are new to Embedded Python, read Introduction to Embedded Python, and then read this document for a deeper dive into Embedded Python.

While this document will be helpful to anyone who is learning Embedded Python, some level of ObjectScript familiarity will be beneficial to the reader. If you are a Python developer who is new to InterSystems IRIS and ObjectScript, also see the Orientation Guide for Server-Side Programming.

Configure Embedded Python

Configuring Embedded Python consists of two main steps:

The version of Python recommended when using Embedded Python depends on the platform you are running. In most cases, the recommended version is the default version of Python for your operating system.

On some operating systems, you can override the default version of Python using the Flexible Python Runtime feature. This is useful if you are writing code or using a package that depends on a particular version of Python. You must use a version of Python that is the same or greater than your operating system's default version, and the version must be supported by the operating system. For example, Red Hat Enterprise Linux 9 comes with Python 3.9, and you may want to use version 3.12.

See Embedded Python Support for a complete list of operating systems and their default version of Python, as well as any versions of Python that have been tested by InterSystems for use for Flexible Python Runtime.

Important:

InterSystems IRIS does not support free threading in Python when used with Embedded Python. Do not disable the global interpreter lock (GIL) if you are using Embedded Python. For more information, see Python support for free threadingOpens in a new tab.

Important:

Users of Microsoft Windows should be aware of the following:

If you are using Windows, you must use the Python standalone installer, not the Python install manager, as you will be installing Python for all users. The Python install manager for Windows does not allow you to install Python for all users.
If you need to use OpenSSL 3 with Embedded Python on Windows, install Python 3.11 or higher. This installs whatever version of OpenSSL 3 is included with the Python installer. (The version of OpenSSL used by Embedded Python is independent from any other versions used by the Windows operating system or by InterSystems IRIS itself.)

Important:

The AutoML feature of IntegratedML requires Python 3.11 or later.

Install a Version of Python to Use for Embedded Python

If you need to install a version of Python for use with Embedded Python, follow the guidelines in this section. See Embedded Python Support for a complete list of operating systems and the corresponding supported version of Python.

Microsoft Windows does not come with a default version of Python, and the InterSystems IRIS installer for Windows no longer installs Python for you. You can install Python from https://www.python.org/downloads/Opens in a new tab. Make sure to use the standalone installer to do a custom installation, and install Python for all users. Then configure the Flexible Python Runtime feature.

Many flavors of UNIX-based operating systems come with Python installed. If you need to install it, use the version recommended for your operating system by your package manager, for example:

Ubuntu: apt install python3
Red Hat Enterprise Linux or Oracle Linux: yum install python3
SUSE: zypper install python3
macOS: Install Python using HomebrewOpens in a new tab.
For example, the following command installs Python 3.11:
brew install [email protected]
You should also make sure you are using the current version of OpenSSL:
```
brew unlink openssl
brew install openssl@3
brew link --force openssl@3
```
AIX: Install Python 3.9.18+ using dnf (dandified yum) from the AIX Toolbox for Open Source SoftwareOpens in a new tab

Note:

If you get an error that says “Failed to load python,” it means that you either don’t have Python installed or an unexpected version of Python is detected on your system. Check Embedded Python Support and make sure you have the required version of Python installed, and if necessary, install it or reinstall it using one of the above methods. Or, override the recommended Python version by using the Flexible Python Runtime feature. (Not available on all platforms.)

Note:

If you are on a platform that does not support the Flexible Python Runtime feature, your computer has multiple versions of Python installed, and you try to run Embedded Python from the command line, irispython will run the first python3 executable that it detects, as determined by your path environment variable. Make sure that the folders in your path are set appropriately so that the required version of the executable is the first one found. For more information on using the irispython command, see Start the Python Shell from the Command Line.

Configure the Flexible Python Runtime Feature

The Flexible Python Runtime Feature allows you to choose which version of Python you want to use with Embedded Python. Flexible Python Runtime is not supported on all operating systems. See Embedded Python Support for a complete list of platforms that support the feature.

Microsoft Windows does not come with Python installed by default, so you must configure the Flexible Python Runtime Feature.

On other operating systems that support the Flexible Python Runtime feature, you can override the default version of Python.

After installing the version of Python you want to use for Embedded Python, follow the steps below to configure InterSystems IRIS to use that version:

In the Management Portal, go to System Administration > Configuration > Additional Settings > Advanced Memory.
On the Advanced Memory Settings page, in the PythonRuntimeLibraryVersion row, click Edit.
Enter the version number (in Major.Minor format) of the Python runtime library you want to use.
For example: 3.14 (not 3.14.x)
Click Save.
On the Advanced Memory Settings page, in the PythonRuntimeLibrary row, click Edit.
Enter the location of the Python runtime library you want to use.
This location will vary based on your operating system, Python version, and other factors.
Windows example: C:\Program Files\Python314\python3.dll (Python 3.14 on Windows)
Linux example: /usr/lib64/libpython3.12.so.1.0 (Python 3.12 on Red Hat 9 on the x86 architecture)
Click Save.

For more information, see PythonRuntimeLibrary and PythonRuntimeLibraryVersion.

Note:

On Microsoft Windows, if you find that the Python runtime library is located within your user directory, for example

C:\Users\<username>\AppData\Local\Programs\Python\Python314

it indicates that you have installed Python for the current user only. InterSystems recommends installing Python for all users to avoid unexpected results.

For more details on how to configure this feature, including step-by-step examples, see Use the Flexible Python Runtime Feature.

Required Service

To prevent IRIS_ACCESSDENIED errors while running Embedded Python, enable %Service_Callin. In the Management Portal, go to System Administration > Security > Services, select %Service_CallIn, and check the Service Enabled box.