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 (PythonEmbed py = PythonEmbed.create()) {
    py.exec("import numpy as np");
    int sum = 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.