Experimental feature in GraalVM

Go here to get started with GraalPy as CPython replacement.

Getting Started with GraalPy on the JVM

You can use GraalPy with GraalVM JDK, Oracle JDK, or OpenJDK. You can easily add GraalPy to your Java application using Maven or Gradle build tools as shown below.

Maven #

GraalPy can generate a Maven project that embeds Python packages into a Java application using Maven artefacts.

  1. Since version 24.0, the GraalPy project publishes a Maven archetype to generate a starter project:
    mvn archetype:generate \
      -DarchetypeGroupId=org.graalvm.python \
      -DarchetypeArtifactId=graalpy-archetype-polyglot-app \
  2. Build a native executable using the GraalVM Native Image plugin that was added for you automatically:
     mvn -Pnative package
  3. Once completed, run the executable:

    The application prints “hello java” to the console.

The project uses the GraalVM SDK Polyglot API with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow. The Java code and the pom.xml file are heavily documented and the generated code describes available features. (If you do not wish to use Maven, the archetype Java code also provides guidance to create a custom embedding.)

Gradle #

  1. Create a Java application with Gradle using the provided command and follow the prompts (select a build script language, select a test framework, etc.):
     gradle init --type java-application \
                 --project-name interop  \
                 --package interop \

    The project is generated in the current working directory with the following structure:

     └── app
         ├── build.gradle
         └── src
             └── main
                 ├── java
                 │   └── interop
                 │       └── App.java
                 └── resources
  2. Open your project configuration file, app/build.gradle, and modify it as follows.
    • Include the GraalPy support and the GraalVM SDK Polyglot API in the dependencies section:

    • We recommend you use the Java modules build. Add the appropriate plugin to the plugins section:
        id("org.javamodularity.moduleplugin") version "1.8.12"
    • To run the application as a module rather than from the classpath, edit the application section to look like this:
        application {
  3. Create a new file named app/src/main/java/module-info.java with the following contents:
     module interop {
         requires org.graalvm.polyglot;
  4. Finally, replace the code in the file named App.java as follows for a small Python embedding:
     package interop;
     import org.graalvm.polyglot.*;
     class App {
         public static void main(String[] args) {
             try (var context = Context.create()) {
                 System.out.println(context.eval("python", "'Hello Python!'").asString());
  5. Run the application with Gradle:
     ./gradlew run

    The application prints “Hello Python!” to the console.

Note: The performance of the GraalPy runtime depends on the JDK in which you embed it. For more information, see Runtime Optimization Support.

Connect with us