FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.2

Introduction

JS7 enables execution of JS7 - GraalVM Python Jobs using the GraalVM Polyglot interface.

The article explains how to install additional Python modules to an Agent using the pip package manager and how to make modules available to Python jobs in a workflow.

The GraalVM Polyglot implementation supports native Python modules only. This means that it is not possible to use modules or functionality that depend on Python’s C-API.
Examples include NumPy, Pandas, Pydantic and standard modules that require access to the C-API. Such modules will not work as usual. For example, the socket, resource, and grp modules cannot be used to their full extent.

If full compatibility with the Python ecosystem is required, then use of GraalVM Polyglot should be avoided and instead a Python Shell job should be used:

#!/usr/bin/python

print("hello world!")
# Write some Python code...

Python Installation on the Agent's Machine

Prerequisites

To prepare the Agent for GraalVM Polyglot execution in a job, the Polyglot libraries must be made available by JS7 - Adding and Updating Graal Libraries to Agents.

Installation

A Python installation is required on the Agent's machine to allow the Agent using local modules that come in addition to the modules that ship with GraalVM Polyglot. This allows installing additional modules that can be made available to the Agent.

When GraalVM Polyglot libraries have been installed on the Agent's machine, users should verify that the Polyglot Python version used with the Agent matches the local Python installation.
To determine versions, a Python job can be created as follows:

import sys

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        version = sys.version
        js7Step.getLogger().info(f"Python version: {version}")

# JS7 log output:
# [INFO] Python version: 3.12.8 (Tue Oct 21 17:51:17 CEST 2025)

Installing on Unix

To install Python on the Agent's machine, the distribution’s package manager can be used to install the appropriate version, or the following example can be used to compile a specific Python version: Python - Setup and building.

Installing on Windows

On Windows, the appropriate version can be downloaded from Python - Releases for Windows.

Creating a venv

A virtual environment is created on top of an existing Python installation, known as the virtual environment’s “base” Python, and by default is isolated from the packages in the base environment. so that only those explicitly installed in the virtual environment are available, for details see Python - Creation of virtual environments (venv).

The following commands create a venv:

# Linux/Unix
python3 -m venv /opt/python3/venv
# or
python -m venv /opt/python3/venv

# Windows | cmd
python -m venv "C:\Users\<user>\Python3\Venv"

Installing Additional Python Modules

The following commands activate a virtual environment in the current shell session and install modules by use of pip.

# Linux/Unix | sh
source /opt/python3/venv/bin/activate

# Windows | cmd
"C:\Users\<user>\Python3\Venv\Scripts\activate.bat"

pip install <module-name>

Setting GraalVM Python Run-time Options

The following argument must be passed to the workflow or job to allow the GraalVM Polyglot implementation locating and including additional modules on the Agent's machine:

The value of the python.PythonPath setting should be adjusted to match the corresponding path of the virtual environment installation and should point to the site-packages directory.

For further information see JS7 - GraalVM Run-time Options.

Use of a Job Resource is recommended as it offers central management of arguments and deployment with workflows, see JS7 - Job Resources.

Resources

Downloads

• A preconfigured Job Resource and workflow are offered from the following links for import to JOC Cockpit:
  • Download Job Resource (upload .json): GraalVMPythonOptions.jobresource.json
  • Download Workflow (upload .json): pdGraalVMPythonModuleExample.workflow.json
    • The workflow includes a job that that installs the jinja2 module to the Agent's machine and a further job that makes use of the module.
• The following workflow will check which Python modules can be imported to a Python job. The workflow can be imported to JOC Cockpit:
  • Download Workflow (upload .json): pdGraalVMPythonModulesCheck.workflow.json.
    • The workflow will generate a list of modules that can be imported and will indicate modules for which import fails.

Links

• JS7 - Job Resources
• JS7 - GraalVM Run-time Options
• JS7 - Adding and Updating Graal Libraries to Agents.
• Python Resources
  • Python - Creation of virtual environments (venv)
  • Python - Releases for Windows
  • Python - Setup and building