Installation#

  1. Install an Anaconda distribution of Python. Note you might need to use an anaconda prompt if you did not add anaconda to the path. Alternatives like miniconda also work just as well.

  2. Open an anaconda prompt / command prompt with conda for python 3 in the path.

  3. To create a new environment for CPU only, run

    conda create -n omnipose 'python==3.10.12' pytorch

    For users with NVIDIA GPUs, add these additional arguments:

    torchvision pytorch-cuda=11.8 -c pytorch -c nvidia

    See GPU support for more details. Python 3.10 is not a strict requirement; see Python compatibility for more about choosing your python version.

  4. To activate this new environment, run

    conda activate omnipose

  5. To install the latest PyPi release of Omnipose, run

    pip install omnipose

    or, for the most up-to-date development version,

    git clone https://github.com/kevinjohncutler/omnipose.git
cd omnipose
pip install -e .

Warning

If you previously installed Omnipose, please run

pip uninstall cellpose_omni && pip cache remove cellpose_omni

to prevent version conflicts. See project structure for more details.

Python compatibility#

We have tested Omnipose extensively on Python version 3.8.5 and have encountered issues on some lower versions. Versions up to 3.10.11 have been confirmed compatible, but we have encountered bugs with the GUI dependencies on 3.11+. For those users with system or global pyenv python3 installations, check your python version by running python -V before making your conda environment and choose a different version. That way, there is no crosstalk between pip-installed packages inside and outside your environment. So if you have 3.x.y installed via pyenv etc., install your environment with 3.x.z instead.

Pyenv versus Conda#

Pyenv also works great for creating an environment for installing Omnipose (and it also works a lot better for installing Napari alongside it, in my experience). Simply set your global version anywhere from 3.8.5-3.10.11 and run pip install omnipose. I've had no problems with GPU compatibility with this method on Linux, as pip collects all the required packages. Conda is much more reproducible, but often finicky. You can use pyenv on Windows and macOS too, but you will need a conda environment for Apple Silicon GPU support (PyPi still lacks many package versions built for Apple Silicon).

GPU support#

Omnipose runs on CPU on macOS, Windows, and Linux. PyTorch has historically only supported NVIDIA GPUs, but has more more recently begun supporting Apple Silicon GPUs. It looks AMD support may be avaiable these days (ROCm), but I have not tested that out. Windows and Linux installs are straightforward:

Your PyTorch version (>=1.6) needs to be compatible with your NVIDIA driver. Older cards may not be supported by the latest drivers and thus not supported by the latest PyTorch version. See the official documentation on installing both the most recent and previous combinations of CUDA and PyTorch to suit your needs. Accordingly, you can get started with CUDA 11.8 by making the following environment:

conda create -n omnipose 'python==3.10.12' pytorch torchvision pytorch-cuda=11.8 \
-c pytorch -c nvidia

Note that the official PyTorch command includes torchaudio, but that is not needed for Omnipose. (torchvision appears to be necessary these days). If you are on older drivers, you can get started with an older version of CUDA, e.g. 10.2:

conda create -n omnipose pytorch=1.8.2 cudatoolkit=10.2 -c pytorch-lts

For Apple Silicon, download omnipose_mac_environment.yml and install the environment:

conda env create -f <path_to_environment_file>
conda activate omnipose

You may edit this yml to change the name or python version etc. For more notes on Apple Silicon development, see this thread. On all systems, remember that you may need to use ipykernel to use the omnipose environment in a notebook.

Where are models stored?#

To maintain compatibility with Cellpose, the pretrained Omnipose models are also downloaded to $HOME/.cellpose/models/. This path on linux is /home/USERNAME/.cellpose/, on macOS /Users/USERNAME/.cellpose/, and on Windows C:\Users\USERNAME\.cellpose\models\. These models are downloaded the first time you try to use them, either on the command line, in the GUI, or in a notebook.

If you would like to download the models to a different directory and are using the command line or the GUI, you will need to always set the environment variable CELLPOSE_LOCAL_MODELS_PATH before you run python -m omnipose ... (thanks Chris Roat for implementing this!).

To set the environment variable in the command line/Anaconda prompt on windows run the following command modified for your path: set CELLPOSE_LOCAL_MODELS_PATH=C:/PATH_FOR_MODELS/. To set the environment variable in the command line on linux, run export CELLPOSE_LOCAL_MODELS_PATH=/PATH_FOR_MODELS/.

To set this environment variable when running Omnipose in a jupyter notebook, run this code at the beginning of your notebook before you import Omnipose:

import os
os.environ["CELLPOSE_LOCAL_MODELS_PATH"] = "/PATH_FOR_MODELS/"

Common issues#

If you receive the error: Illegal instruction (core dumped), then likely mxnet does not recognize your MKL version. Please uninstall and reinstall mxnet without mkl:

pip uninstall mxnet-mkl
pip uninstall mxnet
pip install mxnet==1.4.0

If you receive the error: No module named PyQt5.sip, then try uninstalling and reinstalling pyqt5

pip uninstall pyqt5 pyqt5-tools
pip install pyqt5 pyqt5-tools pyqt5.sip

If you have errors related to OpenMP and libiomp5, then try

conda install nomkl

If you receive an error associated with matplotlib, try upgrading it:

pip install matplotlib --upgrade

If you receive the error: ImportError: _arpack DLL load failed, then try uninstalling and reinstalling scipy

pip uninstall scipy
pip install scipy

If you are having issues with the graphical interface, make sure you have python 3.8.5 installed. Higher versions should also work.

If you are on macOS Yosemite or earlier, PyQt does not work and you won't be able to use the GUI. More recent versions of macOS are fine. The software has been heavily tested on Windows 10 and Ubuntu 18.04, and less well tested on macOS. Please post an issue if you have installation problems.