English | 한국어

PythonEmbed

Run Python code from Java — with full CPython compatibility and zero setup.

PythonEmbed embeds a real CPython interpreter in your JVM application via a subprocess + MessagePack binary protocol — just pure Java and CPython. All C extensions (numpy, scipy, torch) work out of the box.

📚 Full documentation at howtis.github.io/python-embed

Quick Start

=== "Gradle"

Add the Gradle plugin to `build.gradle`:
```groovy
plugins {
id 'io.github.howtis.python-embed' version '1.0.2'
}
pythonEmbed {
packages = ['numpy']
}
dependencies {
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
}
```

=== "Maven"

Add the Maven plugin to `pom.xml`:
```xml
<dependencies>
<dependency>
<groupId>io.github.howtis</groupId>
<artifactId>python-embed-runtime</artifactId>
<version>1.0.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>io.github.howtis</groupId>
<artifactId>python-embed-maven-plugin</artifactId>
<version>1.0.2</version>
<executions>
<execution>
<goals><goal>setup</goal></goals>
</execution>
</executions>
<configuration>
<packages>
<package>numpy</package>
</packages>
</configuration>
</plugin>
</plugins>
</build>
```

Then use it in your Java code:

try (PythonEmbedpy = PythonEmbed.create()) {
py.exec("import numpy as np");
intsum = py.eval("sum([1, 2, 3])").asInt();
System.out.println(sum); // 6
}

The build plugin handles Python installation, venv creation, and package installation at build time.

Key Features

Category	Highlights
Compatibility	Full CPython — numpy, scipy, torch, matplotlib, all C extensions
Setup	Zero manual steps — Gradle plugin auto-downloads Python if needed
Safety	Subprocess isolation — Python crashes never kill the JVM
Performance	MessagePack binary protocol
Concurrency	Auto-scaling pool with async CompletableFuture API
Integration	Spring Boot auto-configuration, Actuator HealthIndicator
Interop	Object handles, Java proxies, callbacks, streaming, batch ops
Observability	Health checks, SLF4J log forwarding, close hooks

📚 Full documentation & API reference →

Modules

• python-embed-gradle-plugin — venv creation, package installation, Python auto-download
• python-embed-maven-plugin — Maven equivalent of the Gradle plugin
• python-embed-runtime — process communication, pool management, type conversion
• python-embed-spring-boot-starter — Spring Boot 3.x auto-configuration (SINGLE/POOL modes)
• python-embed-examples — 13 real-world examples

Building

./gradlew build

Requirements: JDK 17+, Python 3.8+ (auto-downloaded if absent).

License

MIT — see LICENSE for details.