GraalPy as a CPython Replacement

Choosing the GraalPy 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 is distributed as an ahead-of-time compiled native executable, compact in size.

GraalPy provides the following capabilities:

Replacement for CPython. Use GraalPy as a replacement for CPython. It is the most compatible, since it most closely resembles the structure of CPython installation packages.
Unique deployment mode for Python applications. Compile a Python application on GraalPy to a single native binary that embeds all needed resources.
Access to GraalVM’s language ecosystems and tools. GraalPy can run many standard Python tools as well as tools from the GraalVM ecosystem.

GraalPy Distributions

GraalPy is available as GraalPy built on Oracle GraalVM and GraalPy Community.

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

Two language runtime options are available for the Oracle and Community distributions of GraalPy:

Native
- GraalPy is compiled ahead-of-time to a native executable.
- This means that you do not need a JVM to run GraalPy and it is compact in size.
JVM
- You can easily exploit Java interoperability.
- Peak performance may be higher than the native option.

GraalPy Identification

The four GraalPy runtimes are identified as follows, using the general pattern graalpy(-community)(-jvm)-<version>-<os>-<arch>:

	Oracle	Community
Native	graalpy-<version>-<os>-<arch>	graalpy-community-<version>-<os>-<arch>
JVM	graalpy-jvm-<version>-<os>-<arch>	graalpy-community-jvm-<version>-<os>-<arch>

Comparison

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

Installing GraalPy

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

Before running pyenv install, you may need to update pyenv to include the latest GraalPy versions.

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

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.
Uncompress the file and update your PATH environment variable to include to the graalpy-XX.Y.Z-linux-amd64/bin (or graalpy-XX.Y.Z-linux-aarch64/bin) directory.

Note: On Oracle Linux 9, additionally install the libxcrypt library that is required for the GraalPy native runtime: yum install libxcrypt-compat.

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

Before running pyenv install, you may need to update pyenv to include the latest GraalPy versions.

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

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.

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.0.0

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

Find and download a compressed GraalPy installation file from GitHub releases that matches the pattern graalpy-XX.Y.Z-windows-amd64.tar.gz.
Uncompress the file and update your PATH variable to include to the graalpy-XX.Y.Z-windows-amd64/bin directory.

Windows Limitations

The Windows distribution of GraalPy has more limitations than its Linux or macOS counterpart, so not all features and packages may be available.

It has the following known issues:

JLine treats Windows as a dumb terminal, with no autocomplete and limited editing capabilities in the REPL
Interactive help() in the REPL doesn’t work
Inside a virtual environment:
- 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.exe -m pip --no-cache-dir install <pkg>
Running from PowerShell works better than running from CMD, various scripts will fail on the latter

Installing Packages

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.

Create a virtual environment with GraalPy by running the following command:
```
 graalpy -m venv <venv-dir>
```
For example:
```
 graalpy -m venv ~/.virtualenvs/graalpy-24.0.0
```

Activate the environment in your shell session:

 source <venv-dir>/bin/activate

For example:

 source ~/.virtualenvs/graalpy-24.0.0/bin/activate

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

Note: To deactivate the Python environment (and return to your shell), run deactivate.

The pip package installer is available when using a virtual environment. The GraalPy implementation of pip may choose package versions other than the latest in cases where it ships patches to make these work better.