macOS — Step-by-Step Installation¶

← Back to macOS Installation

This page walks you through installing JuSPICE on macOS, one command at a time. You don’t need to be an expert — every command below is something you type into Terminal and press Enter on, and each one is explained in plain language before you run it. The same steps work the same way on both Intel and Apple Silicon (M-series) Macs. Want everything installed in one go instead? See macOS — Install Everything at Once.

JuSPICE needs Python 3.12 (a specific version of the Python programming language) to run. The commands below use a tool called uv, which downloads Python and all of JuSPICE’s required software for you and keeps everything tidy in one folder — you won’t need to install Python separately first.

Prerequisites¶

Install uv (skip this if you already have it):

curl -LsSf https://astral.sh/uv/install.sh | sh

# or via Homebrew
brew install uv

# or via pip
pip install uv

Full installation instructions and platform-specific notes are in the uv documentation. If uv still isn’t found after installing it, or you need uv to install Python 3.12 itself, see macOS Troubleshooting.

Step 1 — Clone the repository¶

“Cloning” downloads a copy of the JuSPICE source code from its online repository onto your computer, into a new folder named juspice:

git clone https://jugit.fz-juelich.de/iet-1/juspice.git
cd juspice

The second command, cd juspice (“change directory”), moves your terminal into that new folder, so every command after this one runs from inside it.

Step 2 — Create a virtual environment¶

A virtual environment is a self-contained folder that holds its own private copy of Python and whatever packages get installed into it — separate from any other Python project on your computer, so installing JuSPICE here can never interfere with anything else you have installed.

JuSPICE keeps its virtual environment (and, if you use it, a second one for a tool called IOPaint) inside the repository itself, under a folder named venvs/. That keeps the whole install self-contained: nothing gets installed outside this one folder, and you never need to edit any shell configuration files (like ~/.zshrc or ~/.bash_profile) to make it work.

Create it:

uv venv venvs/.venv --python 3.12

Then activate it — this tells Terminal “for the rest of this session, use the Python and packages inside venvs/.venv, not any other Python on this Mac”:

source venvs/.venv/bin/activate

After activation, (.venv) appears at the start of your Terminal prompt, confirming it worked. You’ll need to run this source command again every time you open a new Terminal window to work on JuSPICE — it doesn’t stay active forever, only for the current session.

Step 3 — Install dependencies¶

With venvs/.venv active, you can now install JuSPICE and the software it depends on (“dependencies”). You can install just the core package, or add optional feature groups (“extras”) on top — whichever you choose, they all install into the same venvs/.venv you just activated.

Core install¶

The core install gives you preprocessing, feature extraction, clustering, inpainting, physics-based image generation, two of the three synthetic-data generation methods, full provenance tracking (an automatic record of every processing step you run), file loading/saving for every supported format, and the complete notebook collection — all without needing any of the larger, optional deep-learning packages:

uv pip install -e .

Two things are not included in the core install:

The deep-learning accessors (U-Net, SAM-1/2, MicroNet, DCGAN, Stable Diffusion) need the [dl] extra — see the table below.
trackpy (particle tracking) is a special case — see below.

Optional extras¶

Think of an “extra” as an optional add-on pack: a named bundle of additional packages you install only if you actually need the features that depend on them, so you don’t have to download things you’ll never use.

Extra	Packages installed	Required for	Approx. size
`dl`	torch, torchvision, segmentation-models-pytorch, tensorflow, diffusers, transformers, accelerate, peft, segment-anything, sam2	`spice.segmentation.train_unet()`, `spice.segmentation.run_sam1()`, `spice.segmentation.run_sam2()`, `spice.segmentation.run_micronet()`, `spice.synth_generation.generate()` for DCGAN and Stable Diffusion (`example_DCGAN`, `example_SDiff`)	~2.5 GB
`all`	Everything in `dl` above, plus `trackpy`	Full analysis environment, including `spice.segmentation.run_trackpy()`	~2.5 GB (libraries only — see note below)

For what each of these extras — and every pretrained model they can download — actually costs in disk space, see the disk-space note on macOS — Install Everything at Once.

Install an extra by adding its name in square brackets after the package name:

# Deep-learning segmentation pipeline
uv pip install -e ".[dl]"

# Full analysis environment (deep-learning + trackpy)
uv pip install -e ".[all]"

Special cases¶

A few packages need an extra step beyond the table above — either because they aren’t published in the usual place (PyPI, the Python Package Index most installers pull from), or because installing them alongside the extras above would cause version conflicts.

NASA MicroNet pretrained models (required for spice.segmentation.run_micronet()) aren’t published on PyPI, so they have to be installed straight from their GitHub repository:

UV_PROJECT_ENVIRONMENT=venvs/.venv_micronet uv sync --python 3.12 --extra dl
uv pip install --python venvs/.venv_micronet/bin/python \
    git+https://github.com/nasa/pretrained-microscopy-models

This dedicated environment takes about 2.8 GB on disk, on top of everything else (sizes from a test installation by the developer; yours may vary a little).

Trackpy (particle tracking, required for spice.segmentation.run_trackpy()) is included in the all extra above. If you only installed [dl] rather than [all], add it separately:

uv pip install trackpy

If the version on PyPI has compatibility problems with your installed NumPy or Python version, install the latest development version straight from its source code instead:

uv pip install https://github.com/soft-matter/trackpy/archive/master.zip

IOPaint is needed for every synthetic-data method that augments images (Aug, PB, PB_NonGauss, SDiff, DCGAN) — it fills in the background these methods expose.

Stable Diffusion is needed for spice.synth_generation.generate(method_name='SDiff') and spice.inpaint.stable_diffusion().

PyTorch on Apple Silicon — the torch package from PyPI installs correctly on M-series Macs and automatically supports GPU acceleration through Apple’s Metal Performance Shaders (MPS) backend; no separate index or extra flag is needed.

Step 4 — Verify the installation¶

Import the package and print its version string. If this runs with no errors, the install worked:

import juspice
print(juspice.__version__)

To run JuSPICE’s automated test suite — a large collection of small checks that each confirm one specific piece of behavior works correctly:

pytest tests/

pytest finds and runs every test file under tests/, checking that each processing accessor produces the expected results on your machine. Tests that need an optional package you haven’t installed are skipped automatically rather than failing, so this works no matter which extras you chose above.

ruff check juspice tests notebooks

ruff check is a linter — it reads through the juspice, tests, and notebooks code without running it, and flags style problems, unused imports, and likely bugs. This is the “linting” mentioned for the dev extra in the table above.

black --check juspice tests notebooks

black is an automatic code formatter. --check asks it to only report which files don’t match its formatting rules, without changing anything; drop --check and Black will rewrite those files to match automatically.

Troubleshooting¶

If uv or python aren’t found, an unsupported Python version gets picked up, or the install fails partway through, see macOS Troubleshooting for a step-by-step recovery procedure.