GraalVM provides an early-stage implementation of Python 3.7. A primary goal isto support SciPy and its constituent libraries. At this point, the Pythonimplementation is made available for experimentation and curious end-users.

Warning: The support for Python is experimental.Experimental features might never be included in a production version, or mightchange significantly before being considered production-ready.

Installing Python

Python can be installed to a GraalVM build with the gu command. See bin/gu —help for more information.

Running Python

GraalVM implementation of Python targets Python 3.7 compatibility at the moment. While support forthe Python language is still limited, you can run simple Python scripts or commandswith the graalpython binary:

$ graalpython [options] [-c cmd | filename]

If no program file or command is given, you are dropped into a simple REPL.

GraalVM supports some of the same options as Python 3.7 and some additionaloptions to control the underlying Python implementation, the GraalVM toolsand the execution engine. These can be viewed using the following command:

$ graalpython --help --help:tools --help:languages

Installing Supported Packages

Python comes with a tool called ginstall used to install a small list ofpackages known to work to some extent with GraalVM implementation of Python.It is recommended to always create a virtual environment first, using thestandard Python module venv. Creating such an environment avoids anyincompatible interaction with the local user’s packages that may have beeninstalled using a system installation of CPython:

$ graalpython -m venv my_new_venv
$ source my_new_venv/bin/activate

To see the list of installable packages, run:

$ graalpython -m ginstall install --help

This will print a short help including a comma-separated list of packages youcan install. The installation works as described in that help:

$ graalpython -m ginstall install pandas

Note that when using the GraalVM implementation of Python from Java, thepolyglot shell, or another language, you should always evaluate the piece ofPython code first to make installed packages available:

import site

Interoperability

GraalVM supports several other programming languages, including JavaScript, R,Ruby, and LLVM. GraalVM provides a Python API to interact with other languagesavailable on the GraalVM. In fact, GraalVM uses this API internally toexecute Python C extensions using the LLVM implementation in GraalVM.

To run the following script, pass the —jvm —polyglot options tograalpython binary. This makes other GraalVM languages available in scripts.

As a simple example, we can use the JavaScript regular expression engine tomatch Python strings:

import polyglot
re = polyglot.eval(string="RegExp()", language="js")
pattern = re.compile(".*(?:we have (?:a )?matching strings?(?:[!\\?] )?)(.*)")
if pattern.exec("This string does not match"):
    raise SystemError("that shouldn't happen")
md = pattern.exec("Look, we have matching strings! This string was matched by Graal.js")
if not md:
    raise SystemError("this should have matched")
print("Here is what we found: '%s'" % md[1])

If you put this code into a file polyglot_example.py, you can run it with:

$ graalpython --jvm --polyglot polyglot_example.py

This example matches Python strings using the JavaScript regular expression objectand Python reads the captured group from the JavaScript result and prints: Hereis what we found: 'This string was matched by Graal.js'.

As a more complex example, we can read a file using R, process the data inPython, and use R again to display the resulting data image, using both R andPython libraries in conjunction. To run it, first install therequired R library:

$ R -e 'install.packages("https://www.rforge.net/src/contrib/jpeg_0.1-8.tar.gz", repos=NULL)'

This example also uses image_magix.py and workson a JPEG image input. (You can try with thisimage, for example). These files haveto be in the same folder the script below is located in and executed from.

import polyglot
import sys
import time
sys.path.insert(0, ".")
from image_magix import Image
load_jpeg = polyglot.eval(string="""function(file.name) {
    library(jpeg)
    jimg <- readJPEG(file.name)
    jimg <- jimg*255
    jimg
}""", language="R")
raw_data = load_jpeg("python_demo_picture.jpg")
# the dimensions are R attributes; define function to access them
getDim = polyglot.eval(string="function(v, pos) dim(v)[[pos]]", language="R")
# Create object of Python class 'Image' with loaded JPEG data
image = Image(getDim(raw_data, 2), getDim(raw_data, 1), raw_data)
# Run Sobel filter
result = image.sobel()
draw = polyglot.eval(string="""function(processedImgObj) {
    require(grDevices)
    require(grid)
    mx <- matrix(processedImgObj$`@data`/255, nrow=processedImgObj$`@height`, ncol=processedImgObj$`@width`)
    grDevices:::awt()
    grid.raster(mx, height=unit(nrow(mx),"points"))
}""", language="R")
draw(result)
time.sleep(10)

See the Polyglot Reference and theEmbedding documentationfor more information about interoperability with other programming languages.

Tooling

Although GraalVM’s Python implementation is far from complete and cannot run the standard Pythondebugger pdb, the tools that GraalVM itself provides do work.To debug applications in the Chrome browser, for example, you can run a script like so:

$ graalpython --inspect [script-to-debug.py]
Debugger listening on port 9229.
To start debugging, open the following URL in Chrome:
    chrome-devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229/15615099-351e94d1e2db
Please note: This Python implementation is in the very early stages, and can run little more than basic benchmarks at this point.

The graalpython —help:tools command will give you more informationabout tools currently supported on Python.

Native Images and JVM Runtime

By default, GraalVM runs Python from an ahead-of-time compiled binary, yieldingfaster startup time and lower footprint. However, the ahead-of-time compiledbinary only includes the Python and LLVM interpreters. To interoperate withother languages, we had to supply the —jvm argument above. This instructs thelauncher to run on the JVM instead of in the Native Image mode – you will notice alonger startup time.

Python Compatibility

Is GraalVM compatible with the Python language?

GraalVM’s implementation of Python is in the early stages of development. A primary goal is to supportSciPy and its constituent libraries, but we have a long way to go there. At thispoint, the Python implementation is made available for experimentation andcurious end-users. GraalVM currently aims to be compatible with Python 3.7,but it is a long way from there, and it is very likely that any Python programthat requires any imports at all will hit something unsupported.

Is there any progress in GraalVM and Python packages compatibility?

It is too early to claim that there are any Python packages that GraalVM iscompatible with.

Python Command Options

Python is run using the graalpython [option] … (-c cmd | file) [arg] … commandsequence and supports some of the same options as the standard Pythoninterpreter including, but not limited to:

• -c cmd: pass a program as String and terminate options list
• -h, —help: print the help message and exit
• -i, PYTHONINSPECT=x: inspect interactively after running a script and force a prompt even ifstdin does not appear to be a terminal
• -V, —version: print the Python version number and exit
• file: read a program from the script file
• arg …: arguments passed to program in sys.argv[1:]

The following options are mostly useful for developers of the language or toprovide bug reports:

• —python.CoreHome=<String>: The path to the core library of Pythonthat is written in Python. This usually resides in a folderlib-graalpython in the GraalVM distribution.
• —python.StdLibHome=<String>: The path to the standard library thatPython will use. Usually this is in a under lib-python/3 in theGraalVM distribution, but any Python 3.7 standard library location may work.
• —python.WithJavaStacktrace: Prints a Java-level stack trace besides thenormal Python stack when errors occur.

There are a few other debugging options used by the developers of GraalVM,but these change frequently and may not do anything at any given point in time,so any observed effects of them should not be relied upon.