Skip to content
Connecting Java/ImgLib2 + Python/NumPy
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.

Join the chat at


imglyb aims at connecting two worlds that have been seperated for too long:

imglib2-imglyb uses PyJNIus to access numpy arrays and expose them to ImgLib2 through imglib2-imglyb. This means shared memory between numpy and ImgLib2, i.e. any ImgLib2 algorithm can run on numpy arrays without creating copies of the data! For example, Python users can now make use of the BigDataViewer to visualize dense volumetric data. If you are interested in using imglyb, have a look at the imglyb-examples repository and extend the examples as needed! In addition to that, multiple notebooks demonstrate the general use.

Note: NEP 18 has the potential to improve numpy - imglib interoperability, especially when converting imglib2 data structures to numpy.


imglyb is available on conda for Linux, OSX, and Windows:

conda install -c conda-forge -c hanslovsky imglyb

Re-activate the environment after installation to correctly set the environment variables if necessary. If this does not work for you, please follow the build instructions below.


If you choose to install imglyb from source (instead of conda) make sure that these dependencies are present at runtime:


Build Dependencies

  • Python 3
  • Java 8
  • Apache Ant
  • Cython
  • conda (optional, if installing dependencies from conda)
  • git (optional, if installing dependencies from git)
  • GNU Make (Linux/OSX only)

Build Instructions

You can install PyJNIus through conda from the conda-forge channel:

conda install -c conda-forge pyjnius

This will use OpenJDK from conda-forge. If you prefer to use a different JDK, e.g. to use a newer release or for JavaFX projects, you can build PyJNIus from source on your local machine:

Clone (or download) the PyJNIus repository:

# get PyJNIus
git clone
cd pyjnius

In order to build pyjnius.jar and install the pyjnius python package, run on Linux or OSX:

make # creates build/pyjnius.jar
export JAVA_HOME=/path/to/jdk
make tests # optional
python install
# Set the appropriate environment variables:
export JAVA_HOME=/path/to/jdk
export PYJNIUS_JAR=/path/to/pyjnius/build/pyjnius.jar

On Windows:

ant all
python build_ext --inplace -f
python install
:: Set the appropriate environment variables:
SET "PYJNIUS_JAR=path\to\pyjnius\pyjnius.jar"
SET "JAVA_HOME=path\to\jdk"

Note that it can be useful to automate setting up the environment, either through a script or by adding the appropriate lines to a shell config file, e.g. ~/.bashrc or ~/.zshrc for bash on Linux and OSX.

cd /path/to/imglyb
pip install .

Install scyjava through conda

conda install -c hanslovsky scyjava

or install from the latest python branch:

git clone
pip install scyjava


Note that, in your python files, the line

import imglyb

needs to come before any of

from imglyb import util
import jnius
from jnius import *

It is best to follow and extend the imglyb-examples according to your needs.

Known Issues

AWT through PyJNIus on OSX

AWT, PyJNIus, and Cocoa do not get along perfectly. In general, the Cocoa event loop needs to be started before the JVM is loaded. (Thanks to @tpietzsch for figuring this out!) This requires some OS X specific code, written using PyObjC, to properly start up and shut down the Cocoa application and start the Java/Python code within it.

The script included in the imglyb library provides an example of Cocoa code and can be used to run the imglyb-examples. Two packages from PyObjC are required for this wrapper (pyobjc-core and pyobjc-framework-cocoa), and they should be installed with imglib2-imglyb on OS X.

When running the wrapper, one can either provide the name of the target module (as if using python -m) or the full path to the target script. So using the module name, the command to run the "butterfly" script in imglyb-examples looks like this: python imglyb/ imglyb-examples.butterfly

Running via python -m does not work at this time.

You can’t perform that action at this time.