- Latest (GraalVM for JDK 21)
- Dev Build
- GraalVM for JDK 21
- GraalVM for JDK 20
- GraalVM for JDK 17
- GraalVM 22.3
- GraalVM 22.2
- GraalVM 22.1
- GraalVM 22.0
- GraalVM 21.3
- Java on Truffle
- LLVM Languages Reference
- Python Reference
- Jython Compatibility
- Operating System Interfaces
- Installing Packages
- Python Code Parsing and pyc Files
- Python Native Executables
- Python Standalone Applications
- Tooling Support for Python
- Ruby Reference
- R Reference
- WebAssembly Reference
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>-<os>-<arch>.tar.gz # GraalPy Community graalpy-community-<version>-<os>-<arch>.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 the name:
|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 by downloading a compressed GraalPy tarball appropriate for your platform. For GraalPy Community, you can also use
- 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
tar -xzf <archive>.tar.gz
Alternatively, open the file in the Finder.
- Check the version to see if the runtime is active:
pyenv (GraalPy Community only) #
Linux and macOS
The other way to install GraalPy Community on Linux and macOS platforms is to use pyenv, the Python version manager. For example, to install version 23.1.0, run the following command:
pyenv install graalpy-community-23.1.0
Using Conda Forge (GraalPy Community only) #
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
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
- 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:
Several executables are available in the virtual environment, including
You can run simple Python commands or programs with the
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:
graalpy and pass the filename as an argument:
You should see the following output
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
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>
<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.