Installer guide

This page covers the current desktop installers, conda-forge, PyPI and container installation, updates, removal, offline preparation and the files to check when installation fails. For older downloadable versions, use the installer archive.

Choose an installation

Use a desktop installer when you want an application launcher and a private Python environment. The installer does not modify an existing Python installation. It downloads a managed Python 3.12 runtime and the exact spaCR version named by the installer, then checks the environment before replacing an existing working installation.

Use the official conda-forge package when Conda should install spaCR and resolve its desktop and core dependencies. Use pip for the PyPI release when spaCR must live in an existing Python environment, notebook, server or cluster, or when you need a PyPI extra that is not part of the conda package. Python 3.12 currently offers the widest selection of optional scientific packages.

Use a container image when spaCR cannot be installed directly on the host, such as a cluster node, a cloud instance or a shared machine you cannot change, or when an analysis must be rerun later with the same software versions. The images are for the CLI and the pipelines; running the desktop interface in a container is supported only on Linux and is described separately below. On a cluster without Docker, build the same image as an Apptainer or SingularityCE file. For a workstation that has no network access at all, use an offline installer bundle.

Desktop installers

Download the current installer from the spaCR README. The installers require an internet connection while they create the private environment.

Windows 10/11

Run SpaCR-<version>-Windows-Online-Setup.exe. The default per-user location is %LOCALAPPDATA%\spaCR and does not require administrator access. Automatic hardware acceleration is selected by default. It installs a CUDA-capable PyTorch build on compatible NVIDIA systems. On other systems it installs the PyTorch build that uv selects for the detected hardware, which is the CPU build when no supported GPU is detected. Clear the component only when you require the smaller CPU-only installation.

macOS 11 or later

Open SpaCR-<version>-macOS-Universal-Online.pkg. The application is placed in /Applications/spaCR.app. On first launch, a visible Terminal bootstrap creates the private runtime under ~/Library/Application Support/spaCR. The current beta is not notarized. If Gatekeeper blocks it, open System Settings → Privacy & Security and choose Open Anyway for spaCR.

Linux x86-64

Make the downloaded installer executable and run it:

chmod +x SpaCR-*-Linux-x86_64-Online.run
./SpaCR-*-Linux-x86_64-Online.run

The default installation root is ~/.local/share/spacr. The launcher is written to ~/.local/bin/spacr and the desktop entry to ~/.local/share/applications. Add ~/.local/bin to PATH if your shell does not already include it.

Automatic backend selection is the Linux default. It installs CUDA support when compatible NVIDIA hardware is available. To require the smaller CPU-only build instead, run the installer with --torch-backend cpu.

Updating

Download and run the installer for the newer version. Installation is staged and validated before it replaces the active private environment; a failed update leaves the previous working environment in place. Project folders and results are not stored in the installation directory and are not removed by an update.

Update channel and What’s new

Preferences → Modules → Update channel chooses what Help → Check for updates offers. Stable releases (the default) offers PyPI’s latest release. Nightly builds also offers pre-releases and development builds, which arrive sooner and are tested less; withdrawn (yanked) versions are never offered. After an update, the next launch opens What’s new in spaCR with the release notes of every version between the previous and the running one: the notes bundled with the build, plus the published GitHub releases when Release news is on and GitHub can be reached. Help → What’s new… reopens it at any time.

Proxies and corporate certificates

Every download spaCR makes (model weights, updates, plug-ins, pip, uv, conda and the segmentation-backend installers) honours HTTPS_PROXY and REQUESTS_CA_BUNDLE (or SSL_CERT_FILE). To set them inside spaCR instead, fill in Preferences → Modules → Proxy (for example http://proxy.example.org:3128) and Certificate bundle (a PEM file from your IT department). These values override the environment, are kept in ~/.spacr/network.json so command-line runs use them too, and are passed on as HTTPS_PROXY, HTTP_PROXY, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, CURL_CA_BUNDLE, PIP_CERT and GIT_SSL_CAINFO. spacr-doctor has a proxy and certificates row. It checks that the certificate bundle exists and can be read, and that PyPI answers through the configured proxy. A password in the proxy address is masked in its output.

macOS online installation: update and reopen

Choose Help → Check for updates, accept the available update, and confirm that spaCR will be reinstalled in its current environment. spaCR closes, uses the installation’s bundled uv to upgrade its existing private environment, checks the installed version, and reopens automatically. This path keeps the application launcher and environment in place. It does not run the first-use installer or ask its terminal questions again.

The command is the same as the macOS recovery command below, using the actual installation directory. An unsuccessful upgrade or version check is recorded in ~/.spacr/logs/update.log and does not trigger a successful-update relaunch. The update also stops if spaCR cannot finish closing safely. The separate frozen application bundle uses its bundle replacement workflow.

Older installations and full installers

The full installers and other installer update paths look for spaCR installations an earlier installer made and remove them, so that only one installer-made copy remains. They find the Windows online and offline installs, the macOS application and its per-user environment, the Linux online install and the Debian package, together with their launchers, shortcuts, menu entries and uninstall registrations. Environments you created yourself and source checkouts are listed but never removed, and your project folders and results are never touched. If a copy cannot be removed – for example a macOS application in /Applications that needs an administrator – the installer names it and does not install the new version.

To see what it would find without changing anything, run the finder from a spaCR checkout: python spacr/install_cleanup.py find.

Recovering an older desktop installation

Desktop builds at version 1.5.0.1 and earlier, plus the Windows 1.5.0.4 build, can try python -m pip even though their private environment has no pip. If Help → Check for updates reports No module named pip, run the command for the original installation below. It uses the installer’s private uv executable to update that same environment; it needs neither administrator access nor a reinstall.

Linux:

~/.local/share/spacr/bootstrap/uv pip install --upgrade --python ~/.local/share/spacr/venv/bin/python spacr

macOS:

"$HOME/Library/Application Support/SpaCR/bootstrap/uv" pip install --upgrade --python "$HOME/Library/Application Support/SpaCR/venv/bin/python" spacr

Windows PowerShell:

& "$env:LOCALAPPDATA\SpaCR\bootstrap\uv.exe" pip install --upgrade --python "$env:LOCALAPPDATA\SpaCR\venv\Scripts\python.exe" spacr

These are the original installers’ default roots. If a different destination was selected during installation, replace the root before bootstrap and venv with that destination. Installers built from version 1.5.0.5 and later carry the corrected updater and do not depend on python -m pip.

Update an environment installed from conda-forge with:

conda update conda-forge::spacr

Update an environment installed from PyPI with:

python -m pip install --upgrade spacr

For reproducible work, install an exact version instead of following the latest release. Use the command for the package source already installed in the environment, replacing VERSION with a release that source publishes:

conda install conda-forge::spacr=VERSION
python -m pip install "spacr==VERSION"

python -m pip index versions spacr lists the PyPI releases, and conda search -c conda-forge spacr lists the conda-forge builds. conda-forge can trail PyPI by a release or more, so check the source you install from.

Uninstalling

  • Windows: open Settings → Apps → Installed apps → spaCR → Uninstall, or run %LOCALAPPDATA%\spaCR\Uninstall.exe.

  • macOS: run /Library/Application Support/spaCR/uninstall-spacr.sh in Terminal. This removes the application, command launcher and system installer support. Remove ~/Library/Application Support/spaCR separately to delete the per-user private runtime.

  • Linux: run ~/.local/share/spacr/uninstall-spacr.sh. This removes the launcher, desktop entry and private environment.

  • conda-forge: activate the environment and run conda remove spacr.

  • PyPI: activate the environment and run python -m pip uninstall spacr.

Remove the environment itself if it was created only for spaCR.

Uninstalling does not delete microscopy projects, databases or exported results. User preferences, run records and logs under ~/.spacr are also left in place so they can be inspected or reused. Remove that directory separately only if those records are no longer needed.

Clean uninstall (purge)

A purge is opt-in. It also deletes spaCR’s caches, backend environments and user data: ~/.spacr (logs, run records, models, backends, news), ~/.cache/spacr, ~/.config/spacr, ~/.local/state/spacr, ~/spacr-demos, ~/spacr-tutorials, the macOS preferences file, the Windows HKCU\Software\spacr\qt settings, a backends folder named by SPACR_BACKENDS_DIR and every cache moved from Preferences → Storage. It lists everything first and deletes only after you type purge (or pass --yes). Shared caches such as Hugging Face’s and Torch’s own folders, and your projects, are never touched.

  • Windows: run %LOCALAPPDATA%\spaCR\Uninstall.exe /PURGE.

  • macOS: run uninstall-spacr.sh --purge as above.

  • Linux: run ~/.local/share/spacr/uninstall-spacr.sh --purge.

  • Any install, before uninstalling: python -m spacr.install_cleanup purge (add --dry-run to list only).

Portable mode

Portable mode keeps everything spaCR writes for a user next to the application instead of in the home folder: preferences, caches, logs, run records, model downloads, plugins and segmentation backends. Use it to run spaCR from a USB drive or an external disk, or on a shared computer where nothing should be left behind.

Turn it on in either of two ways:

  • Marker file. Create an empty file named spacr-portable in the spaCR install folder, which is the folder that holds spaCR’s Python environment. On Windows that is %LOCALAPPDATA%\spaCR; on macOS ~/Library/Application Support/spaCR; on Linux ~/.local/share/spacr. In a conda or virtual environment, the environment folder itself also works.

  • Environment variable. Set SPACR_PORTABLE=1 to keep data next to the application, or SPACR_PORTABLE=/path/to/folder to choose the folder. SPACR_PORTABLE=0 turns portable mode off even when a marker file exists.

spaCR then keeps its data in a spacr-data folder beside the marker (or inside the chosen folder): settings holds the preferences as an INI file on every platform, so nothing is written to the Windows registry or the macOS preference files, and logs, runs, backends, plugins, models and cache hold the rest. Help → About spaCR shows the folder in use while portable mode is on. Restart spaCR after creating or removing the marker.

Portable mode is one switch for the folder variables that can also be set one at a time. It fills in any of them that are not already set, and a variable you set yourself always wins:

SPACR_HOME

Preferences, run records and every other per-user spaCR folder.

SPACR_LOG_DIR, SPACR_BACKENDS_DIR, SPACR_PLUGIN_HOME

Logs, segmentation backend environments and plugins.

XDG_CACHE_HOME, XDG_STATE_HOME, TORCH_HOME, HF_HOME, MPLCONFIGDIR, CELLPOSE_LOCAL_MODELS_PATH

Caches of example data, chained settings, PyTorch, Hugging Face, Matplotlib and Cellpose models.

Existing data in ~/.spacr is not moved. Copy it into spacr-data first to keep it.

Offline installation

The small desktop installers are online installers and cannot complete without network access. For a locked-down microscope PC, build an offline bundle on a networked machine. It holds everything the installer would download: the pinned uv tool, the managed Python 3.12 runtime, every wheel of the locked environment, Cellpose weights (cpsam by default), optional Mask test data, bundle.json and a SHA256SUMS file. Bundles target linux-x86_64, windows-x86_64 or macos-arm64 and can be built for another platform than the one building them. The PyTorch wheel line is fixed when the bundle is built: cpu, or a CUDA line such as cu126.

From a spaCR checkout, on the networked machine:

python packaging/offline/build_offline_bundle.py --platform linux-x86_64 \
    --torch-backend cpu --out dist/offline \
    --test-data ~/.cache/spacr/example_data/plate1 --archive

This writes the folder spaCR-VERSION-Linux-x86_64-Offline-cpu under dist/offline and, with --archive, the same folder as one .tar. --extras chooses optional spaCR extras (none by default); the standard package includes the Qt desktop interface. --cellpose-model adds Cellpose weights and can be repeated, --test-fields limits the number of test fields, and --from-source . packs spaCR built from the checkout instead of the PyPI release.

Copy the bundle to the offline machine and run its installer with the bundle folder. On Linux or macOS:

./install.sh --offline-bundle "$PWD" --check-mask

On Windows, in PowerShell inside the bundle folder:

.\install.ps1 -OfflineBundle . -CheckMask

The installer checks every file against SHA256SUMS, installs Python and the wheels with no package index, and copies the Cellpose weights without overwriting existing ones. --check-mask (-CheckMask) then runs Mask on a scratch copy of the bundled test data and passes when masks and merged stacks are written; on a CPU this can take an hour for two fields.

What the bundle does not contain: the separate environments of optional segmentation backends such as Cellpose 3 or StarDist, and Model Zoo models other than the Cellpose weights you chose; those still need a network. On Linux the system Qt libraries are not bundled, so a minimal system without them runs spaCR headless only. SHA256SUMS detects damaged files, but the bundle is not signed, so transfer it through a channel you trust.

Install into an existing Python environment

To install spaCR into an existing Python environment offline, prepare a wheel directory on a networked machine with the same operating system, architecture and Python minor version, replacing VERSION with the release to install:

python -m pip download --dest spacr-wheelhouse "spacr==VERSION"

Copy spacr-wheelhouse to the offline machine, create and activate a Python environment, then install without contacting a package index:

python -m pip install --no-index --find-links spacr-wheelhouse \
    "spacr==VERSION"

Repeat the download for the required optional extras. GPU-enabled PyTorch builds may require a separate wheel source, so prepare and test the complete wheelhouse on a matching connected machine before moving it to an isolated system.

Conda-forge installation

Install the official conda-forge package directly into an activated environment. It includes spaCR’s desktop and core dependencies:

conda create -n spacr python=3.12 -y
conda activate spacr
conda install conda-forge::spacr
spacr

PyPI installation and extras

The PyPI package supports Python 3.9 through 3.14 except Python 3.14.1. Choose either a Python virtual environment or a Conda environment for the PyPI release. In both cases, pip installs spaCR; the conda-forge route above uses Conda to install spaCR instead.

For a Python virtual environment, first install Python 3.12, then run:

python3.12 -m venv spacr-venv

Activate the environment on Linux or macOS with:

source spacr-venv/bin/activate

On Windows, create it with py -3.12 -m venv spacr-venv and activate it in PowerShell with:

.\spacr-venv\Scripts\Activate.ps1

In the activated environment, install and open spaCR:

python -m pip install --upgrade pip
python -m pip install spacr
spacr

To install the same PyPI release and desktop interface inside a Conda environment:

conda create -n spacr python=3.12 -y
conda activate spacr
python -m pip install --upgrade pip
python -m pip install spacr

The standard package includes the Qt desktop interface and command-line pipelines. On a headless server, use spacr-run without opening the desktop application. Extras can be combined, for example spacr[czi,nd2,lif]. Common additions are:

Extra

Adds

czi, nd2, lif

Additional microscopy file readers.

napari

Transfer images and masks to napari.

anndata

AnnData and .h5ad export support.

omero

OMERO import support.

trackastra, btrack, ultrack

Optional tracking backends.

boosting

CatBoost and LightGBM classifiers.

numpyro, pymc

Optional Bayesian regression backends.

rapids

RAPIDS acceleration where compatible CUDA wheels are available.

tutorial

Packages used by the interactive tutorial environment.

Container images

Two images are published to the GitHub Container Registry as part of every spaCR release, after that version reaches PyPI. Each one is built and then checked before it is pushed: it must report the version its tag claims, it must not run as root, and it must complete one pipeline run on a synthetic field. An image that fails a check is not published, and the workflow run that built it fails.

The public GHCR package page lists available versions. The commands below use the published 1.5.1.0 images; not every older spaCR release has a container image.

The images run spaCR without a display: the CLI, the pipelines, cluster jobs and reruns of an earlier analysis with a pinned version. Use the platform installers above to install the desktop application.

Image

For

ghcr.io/einarolafsson/spacr:1.5.1.0

CPU only. Runs Linux x86-64 containers with Docker or Podman and needs no GPU driver.

ghcr.io/einarolafsson/spacr:1.5.1.0-cuda12.4

CUDA 12.4. Needs an NVIDIA driver of 550 or newer on the host and the NVIDIA Container Toolkit. Without --gpus it behaves as the CPU image.

:latest and :cpu follow the newest CPU release; :cuda and :cuda12.4 follow the newest CUDA release. Name an exact version for anything you intend to reproduce.

Models and data are mounted at run time; neither is included in the image. A cpsam checkpoint is about 1.2 GB and may be updated between releases, so the image ships none: mount a folder on /models and it becomes both the folder the Model Zoo downloads into and the folder Cellpose loads from. SAMCell and DINOCell are not in the images either, because they pin PyTorch versions that conflict with spaCR’s and with each other; install one inside a running container, or let the Model Zoo install it into an isolated environment of its own.

Install Docker and check the image

Install Docker Desktop or, on a Linux server, Docker Engine. Configure it to run Linux containers. These images target x86-64; a native ARM64 image is not provided.

Check that Docker can start the pinned CPU image and list spaCR’s headless pipelines:

docker pull ghcr.io/einarolafsson/spacr:1.5.1.0
docker run --rm ghcr.io/einarolafsson/spacr:1.5.1.0 spacr --version
docker run --rm ghcr.io/einarolafsson/spacr:1.5.1.0 spacr-run --list

For NVIDIA GPU processing, install the host driver and follow the NVIDIA Container Toolkit installation guide to configure Docker’s NVIDIA runtime. The CUDA image’s host-driver requirement is listed above; the CPU image needs neither the toolkit nor --gpus.

Running a pipeline

These examples use a Linux Bash shell. Prepare a screen folder containing your data and exported settings, and a model-cache folder. The bind mounts make them available inside the container as /data and /models. Paths inside the settings CSV must use these container paths, rather than the host’s paths. Write outputs under /data so they remain in screen after --rm removes the container.

mkdir -p screen "$HOME/.cellpose/models"

docker run --rm \
    --user "$(id -u):$(id -g)" \
    -v "$PWD/screen:/data" \
    -v "$HOME/.cellpose/models:/models" \
    ghcr.io/einarolafsson/spacr:1.5.1.0 \
    spacr-run measure --settings /data/settings/measure_settings.csv

On a GPU host, add --gpus all and use the CUDA tag:

docker run --rm --gpus all \
    --user "$(id -u):$(id -g)" \
    -v "$PWD/screen:/data" \
    -v "$HOME/.cellpose/models:/models" \
    ghcr.io/einarolafsson/spacr:1.5.1.0-cuda12.4 \
    spacr-run mask --settings /data/settings/gen_mask_settings.csv

On Linux, pass --user "$(id -u):$(id -g)" to match your host user and group. Files written to a mounted folder use the container’s user ID; without this option, ownership or permissions may differ from your host account. The images already run as a non-root user, and the entrypoint moves the cache directories somewhere writable when the user ID you pass has no home inside the image.

spacr-run --list prints every module that runs headless, and spacr-run --describe <module> prints what one needs and what it writes. spacr-doctor reports what the container found, including whether the GPU is visible:

docker run --rm --gpus all ghcr.io/einarolafsson/spacr:1.5.1.0-cuda12.4 spacr-doctor

The desktop interface in a container

Linux only, and unsupported elsewhere. The images carry the Qt runtime libraries, so a Linux host running X11 can pass its display socket in:

xhost +SI:localuser:"$(id -un)"
docker run --rm \
    --user "$(id -u):$(id -g)" \
    -e DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v "$PWD/screen:/data" \
    ghcr.io/einarolafsson/spacr:1.5.1.0 \
    spacr

Do not pass the host’s XDG_RUNTIME_DIR in. That path does not exist inside the container, and Qt prints a warning about it at every start; the image makes its own runtime directory under the container’s cache folder instead.

A container rarely has a usable OpenGL context, so the animated backdrop may not draw. safespacr starts the same application with the backdrop and GL switched off, and is the right command when the window is slow or blank:

docker run --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
    ghcr.io/einarolafsson/spacr:1.5.1.0 safespacr

On macOS and Windows this needs a third-party X server and is not tested or supported. Use the desktop installer on those platforms.

Building the images yourself

Build from the repository root; the Dockerfiles expect the checkout as their build context:

docker build -f packaging/docker/Dockerfile.cpu -t spacr:cpu .
docker build -f packaging/docker/Dockerfile.cuda -t spacr:cuda .

--build-arg SPACR_UID=$(id -u) --build-arg SPACR_GID=$(id -g) bakes your own user ID into the image, which is an alternative to passing --user on every run. --build-arg PYTHON_VERSION=3.11 selects a different interpreter. Each image can be checked the way the release workflow checks it:

docker run --rm spacr:cpu spacr --version
docker run --rm spacr:cpu python3 /opt/spacr/smoke_pipeline.py

The second command runs a real pipeline on a synthetic field and reports one line per check; it needs no model, no GPU and no network.

Apptainer and SingularityCE on a cluster

Where a cluster allows Apptainer or SingularityCE but not Docker, repackage the Docker image as one read-only .sif file. Build from the repository root as an ordinary user, with Apptainer 1.2 or newer or SingularityCE 4.0 or newer:

apptainer build --build-arg IMAGE=ghcr.io/einarolafsson/spacr:1.5.1.0 \
    spacr-cpu.sif packaging/apptainer/spacr.def
apptainer build --build-arg IMAGE=ghcr.io/einarolafsson/spacr:1.5.1.0-cuda12.4 \
    spacr-cuda.sif packaging/apptainer/spacr.def

To start from an image you built yourself, add --build-arg BOOTSTRAP=docker-daemon --build-arg IMAGE=spacr:cpu. The build runs the image’s smoke test. If a login node has no user namespaces, build on a workstation and copy the .sif file over. Where /etc/subuid lists you but newuidmap is not installed, add --ignore-subuid.

apptainer run spacr-cpu.sif                          # list the modules
apptainer run spacr-cpu.sif spacr-run mask --settings mask.csv
apptainer run --nv spacr-cuda.sif spacr-doctor       # check the GPU

--nv binds the host NVIDIA driver; the CUDA image needs driver 550 or newer. Unlike Docker, the container runs as you, with your real home mounted: models already in ~/.cellpose/models are found, and run manifests go to ~/.spacr/runs/. $HOME, the current folder and /tmp are available by default; add other data folders with --bind. To use a shared model folder, bind it read-only to /models: --bind /shared/cellpose_models:/models:ro. If a host PYTHONPATH from a conda or module setup leaks into the container, add --cleanenv.

packaging/apptainer/spacr_slurm.sh is a Slurm array job that runs Mask then Measure on one plate per task, from one pair of settings files. Copy it, set SIF, PLATES (a file with one plate folder per line), MASK_SETTINGS and MEASURE_SETTINGS and the #SBATCH lines for your cluster, then submit it:

sbatch --array=0-$(( $(wc -l < plates.txt) - 1 )) spacr_slurm.sh

For a CPU partition, remove the --gres line, replace the GPU_FLAG line with GPU_FLAG= and point SIF at the CPU image.

Troubleshooting

The desktop installers write install.log inside their private installation root. Windows also writes nsis-bootstrap-status.txt if the wrapper fails before the Python bootstrap starts. Runtime logs are under ~/.spacr/logs/spacr.log (the equivalent home directory on Windows).

For a Python installation, run:

python -m pip check
python -c "import spacr; print(spacr.__version__)"
spacr-doctor

Include the installer version, operating system, install.log and the output of spacr-doctor when filing a GitHub issue.