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.2.0</version>
  </dependency>
  <dependency>
      <groupId>org.graalvm.polyglot</groupId>
      <artifactId>python</artifactId>
      <version>24.2.0</version>
      <type>pom</type>
  </dependency>

• Gradle

  implementation("org.graalvm.polyglot:polyglot:24.2.0")
  implementation("org.graalvm.polyglot:python:24.2.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.2.0 using Pyenv, run the following commands:

  pyenv install graalpy-24.2.0

  pyenv shell graalpy-24.2.0

  NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.

  Alternatively, you can download a compressed GraalPy installation file from GitHub releases.

  1. Find the download that matches the pattern graalpy-XX.Y.Z-linux-amd64.tar.gz or graalpy-XX.Y.Z-linux-aarch64.tar.gz (depending on your platform) and download.
  2. Uncompress the file and update your 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.2.0 using Pyenv, run the following commands:

  pyenv install graalpy-24.2.0

  pyenv shell graalpy-24.2.0

  NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.

  Alternatively, you can download a compressed GraalPy installation file from GitHub releases.

  1. Find the download that matches the pattern graalpy-XX.Y.Z-macos-amd64.tar.gz or graalpy-XX.Y.Z-macos-aarch64.tar.gz (depending on your platform) and download.
  2. Remove the quarantine attribute.

     sudo xattr -r -d com.apple.quarantine /path/to/graalpy

     For example:

     sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-24.2.0

  3. Uncompress the file and update your 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.2.0 using Pyenv-win, run the following commands:

  pyenv install graalpy-24.2.0-windows-amd64

  pyenv shell graalpy-24.2.0-windows-amd64

  NOTE: There will be a delay between GraalPy release and its availability on Pyenv. Make sure to update Pyenv.

  Alternatively, you can download a compressed GraalPy installation file from GitHub releases.

  1. Find the download that matches the pattern graalpy-XX.Y.Z-windows-amd64.tar.gz and download.
  2. Uncompress the file and update your 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.2 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

  1. Find and download a compressed GraalPy installation file from GitHub releases that matches the pattern graalpy-jvm-XX.Y.Z-linux-amd64.tar.gz or graalpy-jvm-XX.Y.Z-linux-aarch64.tar.gz (depending on your platform) and download.
  2. Uncompress the file and update your PATH environment variable to include the graalpy-jvm-XX.Y.Z-linux-amd64/bin (or graalpy-jvm-XX.Y.Z-linux-aarch64/bin) directory.
  3. Run your scripts with graalpy --python.EmulateJython.

• macOS

  1. Find and download a compressed GraalPy installation file from GitHub releases that matches the pattern graalpy-jvm-XX.Y.Z-macos-amd64.tar.gz or graalpy-jvm-XX.Y.Z-macos-aarch64.tar.gz (depending on your platform) and download.
  2. Remove the quarantine attribute.

     sudo xattr -r -d com.apple.quarantine /path/to/graalpy

     For example:

     sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-24.2.0

  3. Uncompress the file and update your 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.
  4. Run your scripts with graalpy --python.EmulateJython.

• Windows

  1. Find and download a compressed GraalPy installation file from GitHub releases that matches the pattern graalpy-jvm-XX.Y.Z-windows-amd64.tar.gz.
  2. Uncompress the file and update your PATH variable to include to the graalpy-jvm-XX.Y.Z-windows-amd64/bin directory.
  3. Run your scripts with graalpy --python.EmulateJython.