GraalPy can be used as a standalone Python runtime, providing a drop-in replacement for CPython. This guide covers choosing a distribution, installation, package management, basic usage, and deployment options for standalone GraalPy applications.

GraalPy is available in multiple distributions:

• GraalPy built on Oracle GraalVM provides the best experience with additional optimizations, significantly faster performance, and better memory efficiency. It is licensed under the GraalVM Free Terms and Conditions (GFTC), 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.

The standalone GraalPy runtime is compiled ahead-of-time to a native executable. You do not need a JVM to run it, and it has a compact size, fast startup, and fast time to reach peak performance. For Java interoperability and JVM application embedding, see Embedding Python in Java.

The GraalPy standalone runtimes are identified using the pattern graalpy(-community)<python-version>-<graal-version>-<os>-<arch>:

GraalPy provides a Python 3.12 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 provides the following capabilities:

• CPython-compatible distribution for testing Python code on GraalPy.
• A single native binary packaging mode for Python applications.
• Access to GraalVM language ecosystems and tools.

Note: There may be a delay between GraalPy release and its availability on Pyenv.

The easiest way to install GraalPy on Linux is to use Pyenv (the Python version manager):

# Update pyenv to include latest GraalPy versions (if needed)
pyenv update

# Install GraalPy 25.2.4
pyenv install graalpy-25.2.4

# Use GraalPy for the current shell session
pyenv shell graalpy-25.2.4

1. Download the appropriate binary from GitHub releases:

   • AMD64: graalpy3.12-25.2.4-linux-amd64.tar.gz
   • ARM64: graalpy3.12-25.2.4-linux-aarch64.tar.gz

2. Extract and add it to your PATH environment variable:

   tar -xzf graalpy3.12-25.2.4-linux-amd64.tar.gz
   export PATH="$PWD/graalpy3.12-25.2.4-linux-amd64/bin:$PATH"

Using Pyenv (recommended):

# Install GraalPy 25.2.4
pyenv install graalpy-25.2.4

# Use GraalPy for the current shell session
pyenv shell graalpy-25.2.4

1. Download the binary from GitHub releases.

2. Remove quarantine attribute:

   sudo xattr -r -d com.apple.quarantine /path/to/graalpy
   # For example:
   sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-25.2.4

3. Extract and add it to your PATH environment variable:

   tar -xzf graalpy3.12-25.2.4-macos-aarch64.tar.gz
   export PATH="$PWD/graalpy3.12-25.2.4-macos-aarch64/bin:$PATH"

Warning: The Windows distribution has more limitations than Linux or macOS. Not all features and packages may be available.

1. Download the binary from GitHub releases.

2. Extract and add it to your PATH environment variable:

   # Extract the file and update your PATH environment variable
   # to include the graalpy3.12-25.2.4-windows-amd64/bin directory
   tar -xzf graalpy3.12-25.2.4-windows-amd64.zip
   $env:PATH = "$PWD\graalpy3.12-25.2.4-windows-amd64\bin;$env:PATH"

• PowerShell works better than CMD

The recommended way to use GraalPy is with venv virtual environments:

# Create a virtual environment
graalpy -m venv ~/.virtualenvs/graalpy-25.2.4

# Activate the environment
source ~/.virtualenvs/graalpy-25.2.4/bin/activate

Once in a virtual environment, you can use pip to install packages:

# Install a package
pip install requests

# Install with requirements file
pip install -r requirements.txt

Note: GraalPy's pip implementation may choose different package versions to ensure better compatibility.

To deactivate the virtual environment:

# Return to your normal shell environment
deactivate

Once installed, you can use GraalPy like any other Python interpreter:

# Interactive REPL
graalpy

# Run a Python script
graalpy myscript.py

# Run a module
graalpy -m mymodule

# Execute inline code
graalpy -c "print('Hello from GraalPy!')"

Linux is the recommended platform for GraalPy. The main testing focus is:

• Operating System: Oracle Linux
• CPU Architectures: AMD64 and ARM64
• Primary JDK: Oracle GraalVM

Windows and macOS with GraalVM JDK have less comprehensive testing. Some GraalPy features may not work optimally on these platforms.

See Test Tiers for a detailed breakdown of platform support.