Pyjnius

Common errors

• jnius.JavaException: Class not found 'org/package/MyClass'

  cause 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).
  fix Ensure 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

  cause 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.
  fix Verify 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.

  cause 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.
  fix Set 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)

  cause 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.
  fix Ensure 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.

Warnings

• breaking Python 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.
  Fix: Upgrade your Python environment to 3.8 or newer. Python 3.12+ is fully supported.
• breaking Java 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`.
  Fix: Install 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.
• gotcha Pyjnius 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.
  Fix: Use 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.
• deprecated Pyjnius 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.
  Fix: Consider 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.
• gotcha Building 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.
  Fix: Upgrade 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.

Install

• pip install pyjnius Install latest stable version

Imports

• autoclass
  wrong:

  import jnius; jnius.autoclass(...)

  correct:

  from jnius import 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.

Quickstart

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!')