# GraalPy: Running Python 3.13 on the JVM

> GraalPy is an embeddable Python 3.13 runtime for Java and the JVM, with support for package installation, standalone binaries, and experimental native extensions. It is most suitable when Java interoperability is central and native packages have been checked against GraalPy compatibility.

**oracle/graalpython** — GraalPy – A high-performance embeddable Python 3 runtime for Java

- Repository: https://github.com/oracle/graalpython
- Website: https://www.graalvm.org/python/
- Stars: 1,657 · Forks: 164
- Language: Python
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/oracle-graalpython

## Why GraalPy targets JVM deployment

GraalPy addresses the gap between Python applications and Java platforms. It provides a Python 3.13 compliant runtime on the JVM, allowing Python code to run on GraalVM JDK, Oracle JDK, or OpenJDK. The project is aimed at teams that need Python libraries beside Java services, JVM build tools such as Maven, JVM observability through JFR, or deployment through GraalVM Native Image. It is also relevant to teams migrating Python 2 Jython scripts because the README links to Python's porting guide and documents a special Java integration mode.

GraalPy is not limited to embedded Java processes. The documentation also describes replacing CPython as the command-line interpreter for Python applications and packaging those applications as standalone binaries with dependencies included. This gives the project a broader audience than Java-only embedders. However, the Java integration is the clearest technical distinction. A team adopting it solely for benchmark results would miss that design context, since Java interoperability, package compatibility, and deployment through JVM tooling are its stated priorities.

The README describes pure Python code as production-ready and many native extension modules as experimental. That distinction matters during selection. A Python workload whose dependencies are pure Python presents a different adoption case from an ML stack containing compiled packages, system libraries, or platform-specific extensions.

## GraalPy runtime and package data flow

The runtime executes Python 3.13 code on the JVM and exposes Python through GraalVM's language embedding facilities. For a Java application, Maven or Gradle resolves the polyglot runtime and the Python engine artifact. Application code can then enter the Python context according to the embedding documentation. This shared JVM environment is the basis for calls between Java and Python rather than a separate service boundary.

For command-line use, `pip` remains the package installer. Pure Python packages can generally be installed in the usual way. Packages containing C code often have no GraalPy binary, so GraalPy compiles them during installation. That path changes the deployment prerequisites: build tools must be present, and installation takes longer. The repository includes GitHub Actions under `scripts/wheelbuilder` to help package authors produce binary wheels with the correct dependencies, but the README does not claim that every native package already has a compatible wheel.

GraalPy also emulates Python operating system APIs in Java. According to the README, this gives administrators control over Python libraries' access to system services. The repository separates that subject into `docs/user/Embedding-Permissions.md`, which is the relevant source for detailed permission behavior. GraalPy can also feed Python applications into GraalVM Native Image to produce a standalone binary. These mechanisms place package code, JVM hosting, permissions, and native compilation within one project rather than treating deployment as a separate packaging concern.

## Installing GraalPy and creating a first runtime selection

The README offers pyenv, GitHub releases, Maven Central, and GitHub Actions as acquisition paths. For a local Linux or macOS interpreter, the documented quick installation selects GraalPy 3.13 release 25.3.4.1:

```bash
pyenv install graalpy3.13-25.3.4.1 && pyenv shell graalpy3.13-25.3.4.1
```

This is a real first use because it installs the runtime and selects it in the current shell. The selected interpreter is the foundation for running an existing Python application or installing its dependencies with `pip`. Detailed platform setup is linked from `docs/user/Standalone-Getting-Started.md`.

On Windows, pyenv uses a platform-specific package name:

```bash
pyenv install graalpy3.13-25.3.4.1-windows-amd64
```

For a Java build, Maven receives two dependencies: the generic polyglot runtime and the Python engine. The README lists these exact coordinates:

```xml
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>polyglot</artifactId>
    <version>25.3.4.1</version>
</dependency>
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>python</artifactId>
    <version>25.3.4.1</version>
    <type>pom</type>
</dependency>
```

Gradle is documented with a different embedding coordinate, `org.graalvm.python:python-embedding`. That difference should be preserved when configuring a build.

## Compatibility boundaries for native Python packages

GraalPy's package story is the largest adoption constraint. The README says almost any standard Python feature is supported and states that the CPython test suite passes about 85 percent of its tests on every commit. It also reports installation success for 93 percent of a daily-tested set of 600 commonly depended-on PyPI packages, with more than 65 percent of all package tests passing in aggregate. Those figures describe the project's own compatibility reporting, not a guarantee for every workload. The README directs users to the Python Compatibility Checker for specific packages.

Native extensions are another boundary. Packages such as NumPy and PyTorch are listed as installable examples, and the README also mentions Hugging Face use cases. Those examples do not make every extension release equivalent. Performance and correctness depend on how a native extension interacts with Python, while installation can require compilation and host build tools.

This creates a concrete failure mode for teams adopting by package name alone. A project may select GraalPy because NumPy is supported, only to find that its pinned NumPy or transitive dependency version behaves differently. The correct first check is the Compatibility Checker for the exact dependency set, followed by the project's own tests. GraalPy's daily package testing can identify broad support, but it cannot replace workload-specific verification.

## GraalPy, CPython, and Jython migration paths

CPython is the primary alternative described by the README. Its replacement case assumes that Python 3 application behavior and package availability transfer to GraalPy. GraalPy adds a JVM execution environment, Java interoperability, Maven or Gradle integration, and Native Image packaging. CPython remains the reference interpreter used by the compatibility and benchmark procedures described in the README. GraalPy also claims faster execution for some workloads: the README says pure Python code is often faster after JIT compilation and reports a geometric-mean result of about four times CPython on the Python Performance Benchmark Suite. This is a project-reported claim under a documented command, not a guarantee for an application.

Jython is the migration alternative for existing JVM-hosted Python. The README says most Jython code with Java integration is tied to Python 2 releases. GraalPy instead targets Python 3 and documents `--python.EmulateJython` as a migration aid. The documented setup is to download a `graalpy-jvm-XX.YZ.Z-<platform>.tar.gz` distribution, add it to `PATH`, and then select that mode:

```bash
graalpy --python.EmulateJython
```

This is not a promise that Jython scripts run unchanged. Migration still begins with Python's Python 2 to Python 3 porting guide. The option reduces some integration friction, while language and library changes remain separate work.

## Release maintenance, upgrade cost, and licensing

The repository is not archived, and its last push was on 2026-10-16. Recent releases include `graal-25.4.4`, identified as GraalPy 3.13 25.4.4, on 2026-09-22, `graal-25.3.4`, identified as GraalPy 3.13 25.3.4.1, on 2026-08-25, and `graal-25.2.4`, identified as GraalPy 3.12 25.2.4, on 2026-07-28. The dates show continued repository work and recent releases, but they do not establish compatibility with every package.

An upgrade can affect more than the interpreter version. Java projects must keep Maven or Gradle engine coordinates aligned, while command-line deployments must acquire a matching GraalPy distribution. Native packages may also need new wheels or recompilation. The README's compatibility checker and its wheel-building Actions are therefore part of the maintenance burden, not merely optional project resources.

The README badge links to the Universal Permissive License and classifies it as UPL. The repository instead provides `LICENSE.txt` and `THIRD_PARTY_LICENSE.txt`, so adopters must review those files for the actual terms and included third-party licensing. This description is not legal advice, and the README does not provide a complete interpretation of every dependency license.

## Conclusion

Java platform teams should consider GraalPy after verifying their Python packages and operating system dependencies. Projects that require unrestricted CPython extension compatibility or an already documented JVM-only deployment path should first assess CPython or Jython instead. The first adoption check should be GraalPy's Python Compatibility Checker for the exact package versions required by the application.

## FAQ

### How do I install GraalPy with pyenv?

On Linux or macOS, the README documents installing `graalpy3.13-25.3.4.1` with pyenv and selecting it for the current shell. Windows uses `graalpy3.13-25.3.4.1-windows-amd64`.

### Can GraalPy run Python packages with native extensions?

GraalPy has experimental support for many native extension modules, with NumPy and PyTorch given as installable examples. Packages containing C code are often compiled during installation, so compatible build tools are required and installation can take longer.

### How does GraalPy compare with CPython for Python 3 applications?

GraalPy is intended to work as a drop-in CPython replacement in many cases while adding JVM and Java integration. Package compatibility must still be checked, and the README reports performance differences separately from universal compatibility.

## Sources

- [Issues](https://github.com/oracle/graalpython/issues)
- [oracle/graalpython on GitHub](https://github.com/oracle/graalpython)
- [Project website](https://www.graalvm.org/python/)
- [README](https://github.com/oracle/graalpython/blob/master/README.md)
- [Releases](https://github.com/oracle/graalpython/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oracle-graalpython