Conda Installation - CellProfiler/CellProfiler GitHub Wiki

CellProfiler 4

In general, we advise users to install CellProfiler using pip instead of conda. Installation is Conda is largely untested across different environments.

We have been told by users that the following yaml file works to install CellProfiler 4.2.4 as of August 2022.

name: cp4

channels:
- conda-forge
- anaconda
- bioconda
- defaults

dependencies:
- python=3.8
- pip
- numpy
- matplotlib
- pandas
- mysqlclient
- openjdk
- scikit-learn
- mahotas
- gtk2
- Jinja2=3.0.1
- wxpython=4.1.0
- mysqlclient=1.4.4
- sentry-sdk=0.18.0
- pip:
    - cellprofiler==4.2.4

CellProfiler 3

The instructions below apply to CellProfiler 3.1.9 and earlier versions. Instructions for CellProfiler 4.0 installation will be added shortly for all compatible platforms. Please check out the image.sc forum or our Github issues (and submit new issues as needed) if these instructions fail to work for you.

If you are installing CellProfiler on OS X or Linux and are not already an Anaconda/Miniconda user, please first refer to the pages for your operating system for instructions on installing CellProfiler using pip.

Important notes

As of 10/2019, CellProfiler is in a transition from Python 2 to Python 3. This is not yet reflected in the instructions below because Python 3 is still a moving target and not available in an official release. Please take care when following below instructions when installing a HEAD development revision, as it may reference Python 3 already.

Introduction to Conda

Conda is a package manager that can simplify and self-document the installation of python software from source. Conda also manages programming environments in a manner similar to virtualenv or pyenv. These environments organize a collection of packages for a particular programming purpose, e.g. running CellProfiler from source, and isolates them from other Conda environments. This isolation prevents conflict between packages with the same name, which is common when working with different versions of the same package. For instance, environments can be created for the branches of CellProfiler, so these branches of CellProfiler will run independently of each other just like how git keeps the code branches separated for writing code.

CellProfiler currently runs on Python 2.7, so please to be sure to use Conda for Python 2, not Python 3.

Installation

Install the following:

Git
- The magic behind GitHub, which hosts many open-source projects including CellProfiler.
- If using a Mac, you may need to change security preferences: System Preferences > Security & Privacy > Allow apps downloaded from: > download anyway.
Miniconda
- The minimum set of tools needed to use the Conda package manager. It includes Python and Conda in the installation.
- For Mac and Linux users the installation involves executing a bash script from the command line.
- Windows note: install Miniconda for "Just me", the local user only. Otherwise, using conda will require Administrator Privileges, which on Windows will prevent drag-and-drop functionality in the gui; this is a Windows default security precaution related to the command prompt.
Oracle Java JDK or OpenJDK.

Windows Only

Install the following:

Microsoft Visual C++ Compiler for Python 2.7
- A compiler and set of system headers necessary for producing binary wheels for Python 2.7 packages. Conda is cross-platform in part through the use of Python wheels.

Mac Only

Install the following:

Xcode
- Developer tools for Mac that contains compilers necessary for producing binary wheels for Python 2.7 packages.
- After installing, open Xcode to agree to the license agreement.

Linux (e.g. Ubuntu) Only

Usually no additional packages are required, as git and the compilers are usually part of the base distro. It may be well advised to check that a compiler like gcc, the command git and a newer version of OpenJDK (version 8 is good) are available.

Environment Files

Environment files describe a coding environment in YAML. Here is an example of an environment file for running the CellProfiler master branch:

# run: conda env create -f environment.yml
# run: conda env update -f environment.yml
# run: conda env remove -n cellprofiler
name: cellprofiler
# in order of priority: highest (top) to lowest (bottom)
channels:
  - anaconda
  - goodman # mysql-python for mac
  - bioconda
  - cyclus # java-jdk for windows
  - conda-forge # libxml2 for windows
  - daf # wxpython for linux
# - BjornFJohansson # wxpython for linux not longer available
dependencies:
  - appdirs
  - boto3
  - cython
  - h5py
  - ipywidgets
  - java-jdk
  - joblib
  - jupyter
  - libtiff
  - libxml2
  - libxslt
  - lxml
  - packaging
  - pillow
  - pip
  - python=2
  - pyzmq=15.3.0
  - mahotas
  - matplotlib!=2.1.0,>2.0.0
  - mysqlclient
  - numpy
  - raven
  - requests
  - scikit-image>=0.13
  - scikit-learn
  - scipy
  - sphinx
  - tifffile
  - wxpython=3.0.2.0
  - pip:
    - cellh5
    - centrosome
    - prokaryote==2.4.0
    - javabridge==1.0.15
    - python-bioformats==1.4.0
    - git+https://github.com/CellProfiler/CellProfiler.git@master

Save the above text in a text file with a name such as environment.yml.
1. Mac and Linux users will need to use wxpython=3.0.2.0 from the daf channel. This can be achieved by adding daf to the bottom (lowest priority) of the channels list and replacing wxpython with wxpython==3.0.2.0.
From a command line, cd to the directory that contains the environment file. Then, create the environment with this command, conda env create -f environment.yml.
1. If packages cannot be resolved, adding conda-forge to the bottom (lowest priority) of the channel list might make the packages available to conda.
2. If the installation of javabridge fails with AttributeError: 'NoneType' object has no attribute 'rfind', activate the conda environment (see below) to set JAVA_HOME and run conda env update -f environment.yml to complete the package installation.
3. If the installation of mysqlclient fails with EnvironmentError: mysql_config not found, make sure that mysql_config is installed: https://stackoverflow.com/questions/5178292/pip-install-mysql-python-fails-with-environmenterror-mysql-config-not-found. Then complete the installation with conda env update -f environment.yml.
Verify the creation of the environment with conda info --envs.
Activate this environment with the command activate cellprofiler in Windows and source activate cellprofiler in Mac, where you replace the 'cellprofiler' with whatever path is returned by the previous conda info --envs command.
Once inside the environment, run CellProfiler with cellprofiler in Windows and Linux, and pythonw cellprofiler in Mac.

Using a different branch of CellProfiler

Additional branches of CellProfiler can be built in new environments by updating the name: XXXXX line at the top and git line at the bottom of the example environment file. For example, to run the beta version of CellProfiler (where the branch name is beta rather than master) change the git line as follows:

- "git+https://github.com/CellProfiler/CellProfiler.git@beta#egg=cellprofiler-beta"

Another example for running a feature branch:

- "git+https://github.com/CellProfiler/CellProfiler.git@features/pixel_classifier#egg=cellprofiler-features-pixel_classifier"

Issues

If you receive errors like this when creating your environment

fatal: unable to connect to github.com:

this may be because you are behind a firewall and cloning via git:// is blocked. This is described on Stack Overflow here. You can try changing to cloning via https:// which worked for me, with

git config --global url."https://".insteadOf git://

then re-trying environment creation.

If the first attempt to create the conda environment fails, the next attempt may report that the environment already exists. If this is the case use

conda env update -f environment.yml

Exit the environment with deactivate in Windows and source deactivate in Mac.
If wxpython is causing trouble in Windows, wxpython can be installed directly into the conda env using Christoph Gohlke's Windows wheels
In at least one instance centrosome would not install from within the environment file; running pip install centrosome then running the environment creation again solved the issue.
One user has reported the following issue

despite uninstalling and re-installing the packages it was still using the cached versions which I think had been built with a different version of python(?) Re-installing with pip and the --no-cache flag on the troublesome packages in the conda environment seems to have fixed it.