Getting started


CytoPy assumes you are familiar with Python version 3, have some experience with object-orientated programming, Numpy and Pandas. Preferably you also have some experience with Scikit-Learn and general data science principles.

If the above note is daunting, please don’t fret! There are lots of resources linked below and I believe with 6/8 weeks hard work anyone can grasp enough to start using CytoPy. So if you’re brand new to Python, please start at one of the following resources:


CytoPy is cross-platform compatible but has been tested on Windows 10, Ubuntu 20.04, and Ubuntu 18.04. If you experience issues on other platforms please raise an issue on GitHub.


If you’re familiar with Docker and would like to avoid installing CytoPy and MongoDB on your local system, you can obtains a docker image for CytoPy here.


This docker image comes with Jupyter pre-installed which will launch on port 8888; ensure the port is free before running the image.

Installing MongoDB

Regardless of your operating system, you must install MongoDB on your local machine. Alternatively, you can host your MongoDB database on Mongo Atlas. Connecting to a database on Mongo Atlas from CytoPy will be discussed in the next section.

Installing CytoPy

Step 1: install Python

We recommend installing Anaconda, this is a popular data science platform that bundles Python, R, and very intuitive environment manager together. This also comes with a handy graphical user interface for managing all your software.

Alternatively, you can download and install from For this approach we recommend installing virtualenv (see here for information about venv) to manage your Python environments.

Step 2: setup an environment

If you’re on a Windows machine, then open Anaconda Prompt, either from the start menu or from the Anaconda Navigator. On Linux or Max, open a new terminal. Now create an environment with the following command:

conda create --name CytoPy python=3.8

When prompted say “yes”. This will create an isolated programming environment where we will install CytoPy. When we want to work in this environment we use the following command:

conda activate CytoPy

Step 3: install CytoPy

Inside our environment, we want to call the following in this order:

pip install numpy==1.19
pip install cytopy


It is vital that we install Numpy prior to installing CytoPy. This is because FlowUtils, a vital dependency of CytoPy, requires Numpy to compile necessary C extensions. It is recommended to use pip and not conda to install Numpy and CytoPy.

Step 4: install Jupyter (optional)

Next we recommend you install Jupyter and IPython to interact with CytoPy. You can also use CytoPy in the Python console or using Spyder. To install Jupyter and IPython you can run:

pip install jupyter ipython

To make your CytoPy environment available to Jupyter, you want to run the following:

python -m ipykernel install --user --name=CytoPy

Now when you launch Jupyter Notebooks or Jupyter Lab, our CytoPy environment will be an available kernel.