Skip to content


Subversion checkout URL

You can clone with
Download ZIP


alisonkozol edited this page · 16 revisions

This wiki orients developers to CellProfiler-related resources, the structure of CellProfiler’s code, the details of how modules function, the proper use of settings and their display in the user interface, and how image and object measurements are processed and stored.

Developer resources

Source code

The source code for the CellProfiler project is hosted in Git repositories administered by GitHub. The code can be checked out from these locations:

Deprecated versions, no longer actively developed:

Trunk Builds

We perform regular builds of our source code for both CellProfiler and CellProfiler Analyst. They are not as heavily vetted as our releases, but are available here.

Mailing Lists

There are development lists for the CellProfiler and CellProfiler Analyst tools. These are not high-traffic lists and are intended for discussions or questions ranging from code details to long-term plans for the projects. The mailing lists are hosted on Google Groups:

Release notes

Release note summaries and detailed descriptions are available for each version of CellProfiler.

Bugs and Feature Requests

Most users should use the CellProfiler forum to ask for help and report issues. We monitor the forum and may be able to help you find a workaround for the problem. If you have discovered a new bug, we will take care of filing a bug report on your behalf and include all necessary technical information.

The issue tracker on Github is primarily for developer of CellProfiler and related software. There is a special form for submitting new issues with attachments. If you use this form for reporting bugs, please attach sufficient information to reproduce the bug. For many bugs, it is appropriate to attach a CellProfiler pipeline and an image.


The developer community contributes to a Roadmap for future development of CellProfiler.


Creating/retrieving executables

Running CellProfiler from the command line

For a full list of command-line options, run CellProfiler like this:

python --help

To run CellProfiler 2.X without the graphical user interface, use this:

python -c -r -i ~/my_image_directory -o ~/my_output_directory -p ~/my_pipe.mat

On Mac OS X, to run a compiled install of CellProfiler 2.X without the graphical user interface (add ' --help' to the end to see all the switches),

arch -i386 /Applications//Contents/MacOS/CellProfiler

In a LIMS/cluster environment

This page has a detailed discussion of issues and strategies involving integrating CellProfiler into a LIMS or cluster environment. The page also has a list and explanation of the CellProfiler command-line switches that are designed to be used in an integration.

What if I want to contribute to CellProfiler?

We will be glad to take a look at any code you wish to contribute to the CellProfiler Python project, though we cannot guarantee that the code will be included. New modules can be easily run in CellProfiler as a plugin; see Distributing your Module for more details. A plugin would make sense for feature that are decoupled from all the others, e.g, MeasureTexture has code that operates entirely separately from MeasureObjectSizeShape and if someone were to add another measurement module, it might as well be a plugin.

For more sophisticated features, the situation is more complicated. For example, if someone wrote an improvement to our watershed algorithm, it would fit better as an option to IdentifyPrimaryObjects which would allow them to avoid having to copy the code to do the thresholding and initial segmentation.

In short, the decision as to where code best fits is often pragmatic:

  • If possible, include your code as an extension to a current module, such as by adding a new setting.
  • If your code is not suited for any of the current modules, create a new module with the new functionality.

Also, keep these considerations in mind:

  • Does the method work for many conditions?
  • Is it robust?
  • Are the parameters, if any, difficult to tune?
  • Does it fit the typical CellProfiler time budget (~ 1 minute / megapixel / core)?
  • Does the code scale to large numbers of objects (i.e. no looping over pixels, looping over objects discouraged)?
  • Is the code localized to a single file or a handful of new files (it's harder to take a change that requires a large number of new files or a lot of touches to many existing files)?
  • Does the code come with unit tests?
  • Does the code maintain backwards compatibility for CellProfiler pipelines? See for hints on how to do this.
  • Does it require adding any dependencies to CellProfiler?
  • Does it require compilation?
  • Is it single-threaded? (yes is the correct answer)
  • Does it add complexity that might be confusing for new users?

We also recommend the following:

  • During implementation, try to mimic the style already present in the CellProfiler project source code. See our style guide for more details.
  • Provide test code and test cases. The new functionality should pass current and new tests or give expected results. See the section on tests for more details.
  • If possible, test the code on more than one platform. It is good to combine testing on Windows with testing on Linux, Mac OS X or another Unix platform.
  • Please refer to the Writing a CellProfiler module section of the developer wiki for more details on how to write compatible code for the CellProfiler project.

If we receive a pull request of code meeting the above criteria, a pipeline using the method and some representative images (a hypothetical, not asking you to put this together right now), it would make it easy for us to accept and we'd welcome it. Many such efforts stall out because they omitted these considerations.

Writing a CellProfiler module

Producing the Manual

The following procedure will create a PDF manual composed of the module and non-module help with a table of contents for each

  • Make sure you've svn updated to the head version for the most recent help text.
  • From the CellProfiler directory, run --html. This command will create a folder called located at CellProfiler_Manual_(cp_svn_version) containing the HTML files of svn version (cp_svn_version). If you want a specific output directory, use --html -o (output_dir_path).
  • In Adobe Acrobat, goto File > Create PDF... > From Web Page... This step requires the professional version of Acrobat.
  • Point the URL to the index.html file in the CellProfiler_Manual folder. Also, make sure that Get entire site is selected (click Capture Multiple Levels for Adobe 9.0+ first to get this option)
  • In Settings..
    • Under General, uncheck Place headers and footers on new page
    • Under Page layout, change the margins to 0.25 for all margins
  • Since the images are embedded within the document, the PDF can be rather large. To reduce the file size, re-save the document in Adobe using Document > Reduce File Size and chose the latest version of Acrobat you want the PDF to be compatible with. Choosing Acrobat 4.0 and later will reduce the file to ~1/5 the original size.
  • After creating the PDF, to insert page numbers, do the following with the PDF open in Acrobat Pro
    • Select Document > Header & Footer > Add...
    • Click in the Center Footer Text box and then click Insert Page Number.
    • Set the top and bottom margins to 0.25 inches (or whatever you've chosen for the Page Layout above)
    • Click Page Range Options..., select the Pages from radio button and enter the beginning page for the numbering to begin. This should be the first page after the Table of Contents.
    • Click OK, and then OK again to add the text.

History of CellProfiler 2.0

In 2009, software engineers at the Imaging Platform at the Broad Institute began re-writing MATLAB-based CellProfiler 1.0 and created python-based CellProfiler 2.0, which was released in 2010. Our overall goals were:

  • Backwards compatibility with MATLAB: Create modules with the same functionality as CellProfiler 1.0. Load MATLAB pipeline files and output the same MATLAB measurement files, database files and Excel files as CellProfiler 1.0.
  • Improved user interface: Take advantage of Python to improve CellProfiler's user interface. Change the way module settings are displayed: only the relevant ones appear and, if the settings don't make sense, visual cues tell users what needs to be corrected. Create a test mode that lets you test out different settings.
  • Speed improvements: Improve the speed by using the mathematical libraries in Python (Numpy, Scipy) and compiler tools associated with Python.
  • New algorithms: Develop new thresholding methods and improve on some of CellProfiler 1.0's algorithms. Python plays a big part in this because of its strengths in array processing and its support for high-performance extensions.
  • Interfaces to other imaging packages: Build bridges between CellProfiler and other open-source imaging tools.
  • Improved reliability: Give CellProfiler a richer and more flexible internal structure and develop a test suite to continuously validate CellProfiler's functionality.
  • Public development: Open our SVN repository and accept contributed code from the community.
  • Further summary of the features of CP 2.0 upon release were listed here.

Something went wrong with that request. Please try again.