GitHub - oracle/graalpython: GraalPy – A high-performance embeddable Python 3 runtime for Java

GraalPy, the GraalVM Implementation of Python

GraalPy is a high-performance implementation of the Python language for the JVM built on GraalVM. GraalPy is a Python 3.12 compliant runtime. It has first-class support for embedding in Java and can turn Python applications into fast, standalone binaries. GraalPy is ready for production running pure Python code and has experimental support for many popular native extension modules.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.

If you’re considering contributing to this repository, you need to sign the Oracle Contributor Agreement before we can merge your changes. Also, review the Code of Conduct for contributors.

Why GraalPy?

Low-overhead integration with Java and other languages

Use Python in Java applications on GraalVM JDK, Oracle JDK, or OpenJDK
Use JVM tools like Maven, JFR, or GraalVM Native Image
Manage Python libraries' system access thanks to GraalPy's Java-based emulation of Python OS APIs

Compatible with the Python ecosystem

Runs Python code faster

Getting Started

Embedding GraalPy in Java

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

Gradle

implementation("org.graalvm.polyglot:polyglot:25.0.2")
implementation("org.graalvm.python:python-embedding:25.0.2")

Replacing CPython with GraalPy

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.

Quick Installation:

Linux/macOS: pyenv install graalpy-25.0.2 && pyenv shell graalpy-25.0.2
Windows: pyenv install graalpy-25.0.2-windows-amd64
Manual: Download from GitHub releases

See the complete installation guide for detailed instructions.

Using GraalPy in Github Actions

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

Migrating Jython Scripts to GraalPy

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.

Quick Setup:

Download a GraalPy JVM distribution: graalpy-jvm-XX.Y.Z-<platform>.tar.gz
Extract and add to PATH
Run with: graalpy --python.EmulateJython

See the complete migration guide for detailed instructions.

Examples

^{Java AWT app with Python graph library using JBang | Standalone binary of a Python game by Joey Navarro with all dependencies included.}

Documentation

GraalPy Quick Reference Sheet should help you get started. More GraalPy-specific user documentation is available in docs/user. General documentation about polyglot programming and language embedding is available on the GraalVM website.

Community

The best way to get in touch with us is to join the #graalpy channel on GraalVM Slack or tweet us.

Security

Consult the security guide for our responsible security vulnerability disclosure process.

License

This GraalVM implementation of Python is Copyright (c) 2017, 2026 Oracle and/or its affiliates and is made available to you under the terms the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. This implementation is in part derived from and contains additional code from 3rd parties, the copyrights and licensing of which is detailed in the LICENSE and THIRD_PARTY_LICENSE files.