GraalVM Python Runtime

GraalPy provides a Python 3.10 compliant runtime. A primary goal is to support PyTorch, SciPy, and their constituent libraries, as well as to work with other data science and machine learning libraries from the rich Python ecosystem. GraalPy can usually execute pure Python code faster than CPython, and nearly match CPython performance when C extensions are involved. While many workloads run fine, any Python program that uses external packages could hit something unsupported. At this point, the Python implementation is made available for experimentation and curious end-users. See the FAQ for commonly asked questions about this implementation.

GraalPy Distributions #

As of GraalVM for JDK 21, the Python runtime (GraalPy) is available as a standalone distribution.

A GraalPy standalone built on top of Oracle GraalVM (Oracle GraalPy) is licensed under the GraalVM Free Terms and Conditions (GFTC) license, which permits use by any user including commercial and production use. Redistribution is permitted as long as it is not for a fee. Oracle GraalPy provides the best experience: it comes with additional optimizations, is significantly faster and more memory-efficient.

A GraalPy standalone built on top of GraalVM Community Edition (GraalPy Community) is fully open-source. To distinguish between them, GraalPy Community has the suffix -community in the name.

# Oracle GraalPy
graalpy-VERSION-PLATFORM.tar.gz
# GraalPy Community
graalpy-community-VERSION-PLATFORM.tar.gz

Two language runtime options are available for both Oracle and Community GraalPy: Native and JVM. In the Native configuration, GraalPy is ahead-of-time compiled to a standalone native executable. This means that you do not need a JVM installed on your system to use it and it is size-compact. In the JVM configuration, you can use Java interoperability easily, and peak performance may be higher than the native configuration. A JVM standalone that comes with a JVM has the -jvm suffix in a name: graalpy-jvm-<version>-<os>-<arch>.tar.gz.

Configuration:	Native (default)	JVM
Time to start	faster	slower
Time to reach peak performance	faster	slower
Peak performance (also considering GC)	good	best
Java host interoperability	needs configuration	works

Installing GraalPy #

You can install GraalPy either using a Python manager or downloading a compressed GraalPy tarball appropriate for your platform.

Downloading #

Navigate to GitHub releases and select a desired standalone for your operating system.
Uncompress the archive:
Note: If you are using macOS Catalina and later, first remove the quarantine attribute:
```
 sudo xattr -r -d com.apple.quarantine <archive>.tar.gz
```
Now extract:
```
 tar -xzf <archive>.tar.gz
```
Alternatively, open the file in the Finder.
Check the version to see if the runtime is active:
```
 ./path/to/bin/graalpy --version
```

Using `pyenv` #

Linux and macOS

The other way to install GraalPy on Linux and macOS platforms is to use pyenv, the Python version manager. For example, to install version 23.1.1, run the following command:

# To install Oracle GraalPy  
pyenv install graalpy-23.1.1
# To install GraalPy Community
pyenv install graalpy-community-23.1.1

Another option is to use Conda-Forge. To get an environment with the latest version of GraalPy, use the following command:

conda create -c conda-forge -n graalpy graalpy

Windows

There is a GraalPy preview build for Windows that you can download. It supports installation of pure Python packages via pip. Native extensions are a work in progress.

The Windows build has several known issues:

JLine treats Windows a dumb terminal, no autocomplete and limited editing capabilities in the REPL
Interactive help() in the REPL doesn’t work
Inside venvs:
- graalpy.cmd and graalpy.exe are broken
- pip.exe cannot be used directly
- pip has trouble with cache file loading, use --no-cache-dir
- Only pure Python binary wheels can be installed, no native extensions or source builds
- To install a package, use myvenv/Scripts/python.cmd -m pip --no-cache-dir install <pkg>
Running from PowerShell works better than running from CMD, various scripts will fail on the latter

Running Python #

The best way of using GraalPy is from a venv virtual environment. This generates wrapper scripts and makes the implementation usable from a shell as the standard Python interpreter. To create a venv virtual environment with GraalPy, run the following command in your project directory:

graalpy -m venv <venv-dir>

To activate the environment in your shell session run:

source <venv-dir>/bin/activate

Several executables are available in the virtual environment, including python, python3, and graalpy.

You can run simple Python commands or programs with the graalpy launcher:

graalpy [options] [-c cmd | filename]

For example, start the Python interactive shell from the command line using the command graalpy, then enter the following line at the Python shell prompt (identified by >>>), followed by CR.

>>> print("Hello World!")

You should see the output displayed directly, followed by the Python interactive shell prompt

Hello World!
>>>

Alternatively, you can invoke a Python script. Copy the following content into a file named helloworld.py:

print("Hello World!")

Start graalpy and pass the filename as an argument:

graalpy helloworld.py

You should see the following output

Hello World!

Python Options #

GraalPy supports some of the same options as Python 3.10 as well as some additional options to control the underlying Python runtime, GraalVM’s tools, and the execution engine. These can be viewed using the following command:

graalpy --help --help:tools --help:languages

Interoperability with Java #

The best way to embed GraalPy is to use the GraalVM SDK Polyglot API.

As of GraalVM for JDK 21, all necessary artifacts can be downloaded directly from Maven Central. All artifacts relevant to embedders can be found in the Maven dependency group org.graalvm.polyglot.

To embed GraalPy into a Java host application, add GraalPy as a Maven dependency or explicitly put the JAR on the module path. Below is the Maven configuration for a Python embedding:

<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>polyglot</artifactId>
    <version>23.1.0</version>
</dependency>
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>python</artifactId>
    <version>23.1.0</version>
    <scope>runtime</scope>
    <type>pom</type>
</dependency>

The <scope>runtime</scope> parameter is only necessary if you need the runtime dependency.

Depending on which supported JDK you run embedded GraalPy, the level of optimizations varies, as described here.

Learn more in a dedicated GraalPy Interoperability guide. See also the Embedding Languages documentation on how a guest language like Python can possibly interract with Java.

Installing Supported Packages