Skip to content

Standalone-Getting-Started.md

Latest commit

 

History

History
196 lines (130 loc) · 6.6 KB

Standalone-Getting-Started.md

File metadata and controls

196 lines (130 loc) · 6.6 KB

Using GraalPy as a Standalone Python Runtime

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.

Choosing a GraalPy Distribution

GraalPy is available in multiple distributions:

Distribution Options

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

Runtime

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.

Distribution Identification

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

Distribution Runtime License
Oracle graalpy<python-version>-<graal-version>-<os>-<arch> GFTC
Community graalpy-community<python-version>-<graal-version>-<os>-<arch> UPL

GraalPy Capabilities

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.

Installation

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

Linux (Recommended Platform)

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.0.2
pyenv install graalpy-25.0.2

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

Manual Installation (Linux)

  1. Download the appropriate binary from GitHub releases:

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

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

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

macOS

Using Pyenv (recommended):

# Install GraalPy 25.0.2
pyenv install graalpy-25.0.2

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

Manual Installation (macOS)

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

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

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

Windows

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.1.0-windows-amd64/bin directory
tar -xzf graalpy3.12-25.1.0-windows-amd64.zip
$env:PATH = "$PWD\graalpy3.12-25.1.0-windows-amd64\bin;$env:PATH"

Known Windows Limitations

  • JLine treats Windows as a dumb terminal (no autocomplete, limited REPL editing)
  • Interactive help() in REPL doesn't work
  • Virtual environment issues:
    • graalpy.cmd and graalpy.exe are broken inside venv
    • pip.exe cannot be used directly
    • Use myvenv/Scripts/python.exe -m pip --no-cache-dir install <pkg>
    • Only pure Python binary wheels supported
  • PowerShell works better than CMD

Using Virtual Environments

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

Creating a Virtual Environment

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

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

Installing Packages

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

Running Python Code

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!')"

Platform Support

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.