Install & Compatibility
Where this runs
tested against v1.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.040s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jpype
✓ import jpype
Main module for JVM control and core types.
jpype.imports
✓ import jpype.imports
Enables direct import of Java classes as Python modules (e.g., `from java.lang import String`).
jpype.types
✓ from jpype.types import *
Provides Python representations for Java primitive types like JInt, JString, etc.
This quickstart demonstrates how to initialize the JVM, import a basic Java class (`java.lang.String`), create an instance, call a method, and then shut down the JVM. It highlights the importance of setting the `JAVA_HOME` environment variable for JPype to locate the Java Virtual Machine.
import jpype
import jpype.imports
from jpype.types import *
import os
# Ensure JAVA_HOME is set or provide jvmpath directly
# Example: jvmpath = jpype.getDefaultJVMPath() (only works if JAVA_HOME is configured)
# Or, set it manually (e.g., for Windows: C:\Program Files\Java\jdk-11\bin\server\jvm.dll)
# For Linux/macOS: /usr/lib/jvm/java-11-openjdk/lib/server/libjvm.so or similar
# For robust execution, ensure JAVA_HOME is set in your environment variables.
java_home = os.environ.get('JAVA_HOME', '')
if not java_home:
print("Warning: JAVA_HOME environment variable is not set. JPype might not find the JVM.")
print("Please set JAVA_HOME to your JDK/JRE installation path.")
# Attempt to start without explicit path if JAVA_HOME is missing, might fail
jvm_args = []
else:
print(f"Using JAVA_HOME: {java_home}")
# On some systems, getDefaultJVMPath might still require the full path to libjvm.so/jvm.dll
# For simplicity in quickstart, relying on JAVA_HOME or system default
jvm_args = [] # JPype often infers path if JAVA_HOME is set
# Start the JVM with a minimal classpath
try:
# Using a dummy classpath for demonstration; replace with actual JARs if needed.
# For this simple example, no specific JARs are required beyond standard Java libraries.
jpype.startJVM(jpype.getDefaultJVMPath(), *jvm_args, classpath=[os.environ.get('CLASSPATH', '')])
# Import a Java class
from java.lang import System, String
# Use Java objects and methods
java_string = String("Hello from Java!")
System.out.println(java_string)
# Accessing Java static fields or methods
print(f"Java Version: {System.getProperty('java.version')}")
except Exception as e:
print(f"Failed to start JVM or execute Java code: {e}")
finally:
# Shutdown the JVM
if jpype.isJVMStarted():
jpype.shutdownJVM()
print("JVM shutdown.")
Debug
Known issues
breakingJPype 1.6.0 (and newer versions) officially dropped support for JDK 8. Using JPype 1.6.0 with JDK 8 will result in a RuntimeError. Ensure your Java Runtime Environment (JRE) or Java Development Kit (JDK) is version 11 or later.fixUpgrade your Java installation to JDK 11 or newer. Alternatively, downgrade JPype1 to a version compatible with JDK 8 (e.g., <1.6.0).
affects: >=1.6.0
breakingThe default behavior for Java string conversion changed in JPype 0.8. By default, Java strings are now returned as Java objects, not automatically converted to Python strings. Explicit conversion using `str()` is required if a Python string is desired.fixUse `str(java_object)` to convert Java strings to Python strings. You can also explicitly pass `convertStrings=True` to `jpype.startJVM()` to revert to the old default, though this is discouraged for new code.
affects: >=0.8.0
breakingJava exceptions now derive from Python exceptions directly. Old wrapper types like `jpype.JException` are removed. Catch specific Java exception types (e.g., `java.lang.Exception`) instead of generic `JException`.fixUpdate exception handling to catch actual Java exception classes (e.g., `java.lang.Throwable` for a general catch-all) instead of `jpype.JException`.
affects: >=0.7.0
gotchaThe JVM, once started, cannot be shut down and then restarted in the same Python process. Attempting to do so will result in an error.fixDesign your application to start the JVM once at the beginning of the process and shut it down only when the process exits. For testing or scenarios requiring multiple JVM lifecycles, run each in a separate process.
affects: All versions
gotchaThe `jpype.addClassPath()` function must be called *before* `jpype.startJVM()`. Adding classpath entries after the JVM has started will not take effect for the initial classloader (though `DynamicClassLoader` can add JARs dynamically in later versions).fixEnsure all required JARs and classpath entries are added using `jpype.addClassPath()` before `jpype.startJVM()` is invoked. Verify `JAVA_HOME` and `CLASSPATH` environment variables are correctly set.
affects: All versions
gotchaOn Windows, an `import jpype` can sometimes lead to a segmentation fault (exit code -1073741819 (0xc0000005)) due to race conditions or threading issues related to JVM initialization. This is often observed with specific Python and Java versions.fixEnsure your Python interpreter and JDK/JRE versions are compatible. Check GitHub issues for known combinations. Sometimes, reinstalling JPype1 with `--no-binary :all:` or ensuring `JAVA_HOME` is correctly set can help.
affects: Various versions on Windows
gotchaThe Python interpreter and the Java Virtual Machine (JVM) must have matching architectures (e.g., both 64-bit or both 32-bit). Mismatched architectures will lead to loading errors.fixInstall a Python interpreter and a JDK/JRE that both match your system's architecture (e.g., both 64-bit).
affects: All versions
breakingBuilding JPype1 from source requires a C/C++ compiler (like GCC or Clang) to be installed in the build environment. Without a compiler, the build process for its native extensions will fail.fixEnsure a C/C++ compiler (e.g., `build-essential` on Debian/Ubuntu, or Xcode Command Line Tools on macOS) is installed in the environment where JPype1 is being installed, or ensure pre-built wheels are available for your platform to avoid source compilation.
affects: All versions (when building from source)
gotchaThe library failed to build due to missing C/C++ compilers in the environment. Many minimal Docker images (e.g., Alpine Linux) do not include essential build tools like `gcc` by default, which are required to compile JPype1's native extensions.fixEnsure your environment has the necessary C/C++ compilers and build tools installed. For Alpine Linux, this typically means running `apk add build-base`. For Debian/Ubuntu-based systems, install `gcc` and `g++` (e.g., `apt-get update && apt-get install -y gcc g++`).
affects: All versions (that require compilation)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jpype'
The `jpype1` package is either not installed, or there is a common confusion between the package name `jpype1` (used for installation) and the module name `jpype` (used for importing).
fixEnsure the package is correctly installed using `pip install jpype1`. If using Python 3, explicitly use `pip3 install jpype1` or `python3 -m pip install jpype1` to avoid installing for the wrong Python version.
OSError: JVM DLL not found: <path_to_jvm_dll>
JPype cannot locate the Java Virtual Machine (JVM) dynamic link library (e.g., `jvm.dll` on Windows, `libjli.dylib` on macOS). This is often due to an incorrect `JAVA_HOME` environment variable, an architecture mismatch between Python and Java (e.g., 32-bit Python with 64-bit Java), or the specified JVM path being incorrect or inaccessible.
fixVerify that `JAVA_HOME` is set correctly to your JDK/JRE installation directory. Ensure that the Python interpreter and Java installation have matching architectures (both 64-bit or both 32-bit). If specifying the JVM path manually, ensure it points directly to the `jvm.dll` or `libjli.dylib` file within your Java installation (e.g., `jpype.startJVM('/path/to/jdk/jre/bin/server/jvm.dll')`). jpype._jclass.NoClassDefFoundError: <YourJavaClass>
JPype successfully started the JVM, but it cannot find the specified Java class. This usually happens because the `.jar` file containing the class, or the directory with the compiled `.class` file, is not included in the Java classpath when the JVM is started.
fixWhen calling `jpype.startJVM()`, pass the path to your `.jar` files or class directories using the `classpath` argument, for example: `jpype.startJVM(jpype.getDefaultJVMPath(), classpath=['path/to/your.jar', 'path/to/your/classes'])`.
A fatal error has been detected by the Java Runtime Environment (JVM crashes during jpype.startJVM())
The Java Virtual Machine crashed during startup or early operation. This can be caused by severe configuration issues, such as incompatible Java versions, a corrupt Java installation, conflicting JVM options, or deeply rooted architecture mismatches that are not caught by the initial `JVM DLL not found` check.
fixEnsure your Java installation is healthy and compatible with your operating system and Python version. Check `JAVA_HOME` environment variable. Try starting the JVM with minimal options. If on Windows, ensure the JRE's `bin` directory is in your system's `PATH`. Enable JPype stack traces (`_jpype.enableStacktraces(True)`) for more detailed diagnostics if available in your JPype version.
ImportError: cannot import name 'YourJavaClass' from 'your.java.package'
When using `jpype.imports`, a name conflict exists between a Java package/class and an existing Python module, script, or directory with the same name in your Python's import path. Python's import mechanism prioritizes its own modules over JPype's virtual Java modules.
fixAvoid naming your Python files or modules the same as Java packages/classes you intend to import. If renaming is not an option, you can use `JClass('your.java.package.YourJavaClass')` directly instead of `from your.java.package import YourJavaClass`, or register a custom domain alias using `jpype.imports.registerDomain()`. Upgrade
Version history
1.7.1latest on PyPI · released May 19, 2026
Audit
Dependencies
packagingrequiredUsed for package metadata and version handling.
Java Runtime Environment (JRE) or Java Development Kit (JDK) >= 11requiredRequired to run Java code and the JVM.