GraalPy is a high-performance implementation of the Python language for the JVM built on GraalVM . GraalPy has first-class support for embedding in Java and can turn Python applications into fast, standalone binaries.
Low-overhead integration with Java and other languages
Compatible with the Python ecosystem
Runs Python code faster
pip install pyperformance && pyperformance run
on each of CPython and GraalPy.
Harness and benchmarks were adapted by hand for Jython due to missing Python 3 support.
Each interpreter was installed via
pyenv
.
Geomean speedup was calculated against CPython on the intersection of benchmarks that run on all interpreters.
GraalPy is available on Maven Central for inclusion in Java projects. Refer to our embedding documentation for more details.
Maven
<dependency>
<groupId>org.graalvm.polyglot</groupId>
<artifactId>polyglot</artifactId>
<version>24.0.0</version>
</dependency>
<dependency>
<groupId>org.graalvm.polyglot</groupId>
<artifactId>python</artifactId>
<version>24.0.0</version>
<type>pom</type>
</dependency>
Gradle
implementation("org.graalvm.polyglot:polyglot:24.0.0")
implementation("org.graalvm.polyglot:python:24.0.0")
GraalPy should in many cases work as a drop-in replacement for CPython.
You can use
pip
to install packages as usual.
Packages with C code usually do not provide binaries for GraalPy, so they will be automatically compiled during installation.
This means that build tools have to be available and installation will take longer.
We provide
Github actions
to help you build binary packages with the correct dependencies.
Thanks to our integration with GraalVM Native Image, we can deploy Python applications as
standalone binary
, all dependencies included.
Linux
The easiest way to install GraalPy on Linux is to use Pyenv (the Python version manager). To install version 24.0.0 using Pyenv, run the following commands:
pyenv install graalpy-24.0.0
pyenv shell graalpy-24.0.0
Alternatively, you can download a compressed GraalPy installation file from GitHub releases .
PATH
environment variable to include the
graalpy-XX.Y.Z-linux-amd64/bin
(or
graalpy-XX.Y.Z-linux-aarch64/bin
) directory.
macOS
The easiest way to install GraalPy on macOS is to use Pyenv (the Python version manager). To install version 24.0.0 using Pyenv, run the following commands:
pyenv install graalpy-24.0.0
pyenv shell graalpy-24.0.0
Alternatively, you can download a compressed GraalPy installation file from GitHub releases .
sudo xattr -r -d com.apple.quarantine /path/to/graalpy
sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-24.0.0
PATH
environment variable to include to the
graalpy-XX.Y.Z-macos-amd64/bin
(or
graalpy-XX.Y.Z-macos-aarch64/bin
) directory.
Windows
The Windows support of GraalPy is still experimental, so not all features and packages may be available. The easiest way to install GraalPy on Windows is to use Pyenv-win (the Python version manager for Windows). To install version 24.0.0 using Pyenv-win, run the following commands:
pyenv install graalpy-24.0.0-windows-amd64
pyenv shell graalpy-24.0.0-windows-amd64
Alternatively, you can download a compressed GraalPy installation file from GitHub releases .
PATH
variable to include to the
graalpy-XX.Y.Z-windows-amd64/bin
directory.
The setup-python action supports GraalPy:
- name: Setup GraalPy
uses: actions/setup-python@v5
with:
python-version: graalpy # or graalpy24.0 to pin a version
Most existing Jython code that uses Java integration will be based on a stable Jython release—however, these are only available in Python 2.x versions. To migrate your code from Python 2 to Python 3, follow the official guide from the Python community . GraalPy provides a special mode to facilitate migration. To run Jython scripts, you need to use a GraalPy distribution running on the JVM so you can access Java classes from Python scripts.
Linux
PATH
environment variable to include the
graalpy-jvm-XX.Y.Z-linux-amd64/bin
(or
graalpy-jvm-XX.Y.Z-linux-aarch64/bin
) directory.
graalpy --python.EmulateJython
.
macOS
sudo xattr -r -d com.apple.quarantine /path/to/graalpy
sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-24.0.0
PATH
environment variable to include to the
graalpy-jvm-XX.Y.Z-macos-amd64/bin
(or
graalpy-jvm-XX.Y.Z-macos-aarch64/bin
) directory.
graalpy --python.EmulateJython
.
Windows
PATH
variable to include to the
graalpy-jvm-XX.Y.Z-windows-amd64/bin
directory.
graalpy --python.EmulateJython
.
GraalPy Quick Reference Sheet should help you get started. More GraalPy-specific user documentation is available in docs/user . General documentation about polyglot programming and language embedding is available on the GraalVM website.
The best way to get in touch with us is to join the
#graalpy
channel on
GraalVM Slack
or
tweet us
.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide .
If you're thinking about contributing something to this repository, you will need to sign the Oracle Contributor Agreement for us to able to merge your work. Also take a look at the code of conduct for contributors.
Consult the security guide for our responsible security vulnerability disclosure process.
This implementation is in part derived from and contains additional code from 3rd parties, the copyrights and licensing of which is detailed in the LICENSE and THIRD_PARTY_LICENSE files.