Install & Compatibility
Where this runs
tested against v1.7.0 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
autoclass
✓ from jnius import autoclass
✗ import jnius; jnius.autoclass(...)
While `import jnius` works, `from jnius import autoclass` is the canonical and clearer import for the primary function.
JavaClass, MetaJavaClass, JavaMethod, PythonJavaClass
✓ from jnius import JavaClass, MetaJavaClass, JavaMethod
Used for advanced scenarios like subclassing Java classes in Python or implementing Java interfaces.
This example demonstrates how to use `autoclass` to reflect and interact with standard Java classes like `java.util.Stack` and `java.lang.System`. It shows how to instantiate objects, call methods, and access static fields.
from jnius import autoclass
# Access a standard Java class
Stack = autoclass('java.util.Stack')
stack = Stack()
stack.push('hello')
stack.push('world')
print(f"Popped: {stack.pop()}")
print(f"Popped: {stack.pop()}")
# Access static methods and fields
System = autoclass('java.lang.System')
System.out.println('Hello from Pyjnius!')
Debug
Known issues
breakingPython 3.7 is no longer officially supported by Pyjnius 1.7.0. Version 1.6.0 was the last to likely support it. Using Pyjnius with Python 3.7 or older may lead to build or runtime errors.fixUpgrade your Python environment to 3.8 or newer. Python 3.12+ is fully supported.
affects: <= 1.6.x (Python 3.7)
breakingJava Development Kit (JDK) is a mandatory prerequisite. Pyjnius needs a JDK installed on your system to compile and run. The `JAVA_HOME` environment variable must be correctly set, especially on Windows, so Pyjnius can locate the `jvm.dll` or `libjvm.so`.fixInstall a compatible JDK (OpenJDK is recommended) and set the `JAVA_HOME` environment variable to its installation path. On Windows, ensure the JRE's `bin/server` directory containing `jvm.dll` is in your PATH.
affects: All versions
gotchaPyjnius 1.6.0 removed support for Java 7 and added support for Java 20. Ensure your Java code (e.g., `.jar` files) is compiled with a Java version compatible with the JVM Pyjnius uses at runtime.fixUse a compatible JDK for both Pyjnius and your Java artifacts. If you encounter 'Class not found' errors, check if your Java classes were compiled with a newer Java version than the JVM loaded by Pyjnius.
affects: >= 1.6.0
deprecatedPyjnius 1.6.0 was likely the last release to ship with 32-bit pre-built wheels for Windows. Future versions may require manual compilation or only offer 64-bit wheels.fixConsider upgrading to a 64-bit Python environment on Windows if possible. If not, be prepared to build Pyjnius from source or check for community-maintained 32-bit wheels.
affects: >= 1.6.0 (32-bit Windows)
gotchaBuilding Pyjnius from source (e.g., if no pre-built wheel is available for your platform/Python version) requires Cython. Older Pyjnius versions might have compilation issues with Cython 3.x.fixUpgrade Pyjnius to 1.6.0 or newer, which supports both Cython < 3 and Cython >= 3. Alternatively, use an older Cython version (e.g., < 3) if stuck on an older Pyjnius.
affects: < 1.6.0 (with Cython >= 3.0)
Errors
Common errors & fixes
jnius.JavaException: Class not found 'org/package/MyClass'
The specified Java class or JAR file is not found in the JVM's classpath, or the class name is malformed (e.g., using '.' instead of '/' for nested classes, or including '.class' suffix).
fixEnsure your Java class or JAR is correctly compiled and its path is added to Pyjnius's classpath using `jnius_config.add_classpath()` before `autoclass` is called. Use '/' for nested classes (e.g., `java.util.Map$Entry`). Do not append '.class' to the class name.
java.lang.NoClassDefFoundError
Similar to 'Class not found', this usually means the JVM cannot locate the class definition. This can also happen if a class depends on another class that is missing, or if there's a Java version mismatch between compilation and runtime.
fixVerify all required JARs are in the classpath. Check that the Java classes were compiled with a compatible Java version (e.g., compiling with Java 11 and running on JVM 8 can cause issues). For Android, ensure `pyjnius` is in your `buildozer.spec` requirements.
ImportError: DLL load failed: The specified module could not be found.
This error, common on Windows, indicates that Pyjnius cannot find the Java Virtual Machine's dynamic link library (`jvm.dll`). This is usually due to `JAVA_HOME` being unset or incorrectly configured.
fixSet the `JAVA_HOME` environment variable to your JDK installation directory (e.g., `C:\Program Files\Java\jdk-17`). Ensure the `%JAVA_HOME%\jre\bin\server` (for older JDKs) or equivalent path containing `jvm.dll` is in your system's `PATH` environment variable.
error: subprocess-exited-with-error (during pip install)
This typically occurs when pip attempts to build Pyjnius from source because a pre-built wheel is unavailable, and required build tools (like a JDK or Cython) are missing from the system or not properly configured.
fixEnsure a JDK is installed and `JAVA_HOME` is set. Also, ensure Cython is installed (`pip install Cython`). If specific Python versions or architectures lack wheels, you might need to resolve system-level build dependencies like GCC on Linux.
Upgrade
Version history
1.7.0latest on PyPI · released Sep 8, 2025
Audit
Dependencies
No dependency data recorded yet.