This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.

GraalPy as a CPython Replacement

Choosing the GraalPy Runtime #

GraalPy provides a Python 3.11 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 #

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

Linux #

The easiest way to install GraalPy on Linux is to use Pyenv (the Python version manager). To install version 24.1.0 using Pyenv, run the following commands:

pyenv install graalpy-24.1.0

pyenv shell graalpy-24.1.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.

macOS #

The easiest way to install GraalPy on macOS is to use Pyenv (the Python version manager). To install version 24.1.0 using Pyenv, run the following commands:

pyenv install graalpy-24.1.0

pyenv shell graalpy-24.1.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.1.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.1.0
```

Activate the environment in your shell session:

 source <venv-dir>/bin/activate