ImageJ & Fiji¶

This documentation describes how to use ImageJ as a Python package (pyimagej) for image processing and automation. pyimagej allows you to integrate ImageJ's powerful image analysis tools into Python workflows.

For more details, refer to the official documentation:

https://py.imagej.net/en/latest/

For this uv and direnv are used:

uv: is a fast Python package installer and virtual environment manager. It ensures compatibility and speeds up the setup process.
direnv: automatically loads and unloads environment variables based on the current directory.

Create and setup a project directory¶

Use uv to set up a project directory (e.g., imagej_project) with the correct Python version and install pyimagej.

Warning

Avoid naming the project directory the same as the package (e.g., pyimagej). uv may raise an error or behave unexpectedly.

uv init --python=3.13 imagej_project
cd imagej_project
uv venv
uv add pyimagej

Configure `direnv` for automatic virtual environment activation¶

To ease the activation of the virtual environment configure en enable direnv inside the project directory. After enabling the virtual environment will be activated upon entering the directory or its subdirectories.

cat << EOF > .envrc
source .venv/bin/activate
EOF
direnv allow

Test the installation¶

You can now test the pyimagej package in Python. The following example initializes ImageJ in headless mode (without a GUI) and prints the version:

test.py

import imagej
ij = imagej.init(mode="headless")
print(ij.getVersion())

python test.py
# Output: 2.17.0/1.54p

Troubleshooting¶

If uv fails to install pyimagej, ensure you have the latest version of uv and a compatible Python version.
To deactivate the virtual environment, run deactivate.

Further Resources¶

Please read the documentation in the links above for information on how to use pyimagej.