Skip to content

Conda Installation

Matthew Bowden edited this page Sep 7, 2018 · 55 revisions

We advise Conda installation for Windows environments. 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.

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.


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.
  • Java JDK

Windows Only

Install the following:

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


  • git and everything else you need is part of the base distro.

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)
  - anaconda
  - goodman # mysql-python for mac
  - bioconda
  - cyclus # java-jdk for windows
  - conda-forge # libxml2 for windows
  - BjornFJohansson # wxpython for linux
  - 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=
  - pip:
    - cellh5
    - centrosome
    - inflect
    - prokaryote==2.4.0
    - javabridge==1.0.15
    - python-bioformats==1.4.0
    - git+
  1. 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= from the bjornfjohansson channel. This can be achieved by adding bjornfjohansson to the bottom (lowest priority) of the channels list and replacing wxpython with wxpython==
  2. 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: Then complete the installation with conda env update -f environment.yml.

  3. Verify the creation of the environment with conda info --envs.

  4. 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.

  5. 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+"

Another example for running a feature branch:

- "git+"


  • If you receive errors like this when creating your environment

fatal: unable to connect to

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.

You can’t perform that action at this time.