As mentioned in the index, HistomicsTK can be used both as a pure Python toolkit for algorithm development and as server-side Girder plugin for web-based analysis. Here, we describe how to install HistomicsTK for both these scenarios.

Installing HistomicsTK as a Python toolkit

HistomicsTK depends on large_image for reading large multi-resolution whole-slide images in a tiled fashion. Please see the Github repo of large_image to find out how to install it as a Python toolkit/package.

Once large_image is installed as a python package, HistomicsTK can be installed as follows:

$ git clone
$ cd HistomicsTK
# pip install git+
$ pip install --no-cache-dir -r requirements.txt
$ pip install -e .

If you want the keras/tensorflow based functions of HistomicsTK to take advantage of the GPU, then you will have to install the GPU version of tensorflow (tensorflow-gpu) after installing HistomicsTK. See tensorflow installation instructions here.

We are working on releasing HistomicsTK on PyPI so it can easily be pip installed from there.

Installing HistomicsTK as a server-side Girder plugin

When HistomicsTK is used as a server-side Girder plugin for web-based analysis, the following three Girder plugins need to be installed:

  • girder_worker: A Girder plugin for distributed task execution.
  • large_image: A Girder plugin to create/serve/display large multi-resolution images produced by whole-slide imaging systems and a stand-alone Python package to read/write these images.
  • slicer_cli_web: A Girder plugin for providing web-based RESTFul access to image analysis pipelines developed as slicer execution model CLIs and containerized using Docker.

There are several methods that can be used to install HistomicsTK. Each of these results in a fully deployed system. Docker is often the easiest deployment. Vagrant is the easiest development environment.

Installing via Docker

This method should work on any system running Docker. It has been tested with a variety of Ubuntu and CentOS distributions.


Install git, python-pip, and On Ubuntu, this can be done via:

sudo apt-get update
sudo apt-get install git python-pip

The current user needs to be a member of the docker group:

sudo usermod -aG docker `id -u -n`

After which, you will need to log out and log back in.

Install the python docker module:

sudo pip install docker

Get the HistomicsTK repository:

git clone


cd HistomicsTK/ansible
python start

There are many options that can be used along with the command, use --help to list them.

By default, the deployment places all database, log, and assetstore files in the ~/.histomicstk directory. HistomicsTK is run on localhost at port 8080.

Update an installation

cd HistomicsTK/ansible
# Make sure you have the latest version of the deploy_docker script
git pull
# Make sure you have the latest docker images.  This uses the pinned
# versions of the docker images -- add --latest to use the latest built
# images.
python pull
# stop and remove the running docker containers for HistomicsTK
python rm
# Restart and provision the new docker containers.  Use the same
# command-line parameters as you originally used to start HistomicsTK the
# first time.
python start

Installing via Vagrant

This method can work on Linux, Macintosh, or Windows.


Install VirtualBox, Vagrant, and git:

Get the HistomicsTK repository:

git clone


cd HistomicsTK
vagrant up

The Girder instance can then be accessed at http://localhost:8009. Any image placed in the sample_images subdirectory of the directory where HistomicsTK is cloned directory will be seen in the TCGA collection of Girder.

The front-end UI that allows you to apply analysis modules in HistomicsTK’s docker plugins on data stored in Girder can be accessed at http://localhost:8009/histomicstk.

You can also ssh into the vagrant virtual box using the command vagrant ssh. HistomicsTK and its dependencies are installed at the location /opt/histomicstk.

Run tests

Log in to the vagrant box:

vagrant ssh

Inside the vagrant box, tests can be run by typing:

cd /opt/histomicstk/build
ctest -VV

Local installation on Ubuntu 16.04

Due to the library dependencies of OpenJPEG, libtiff, OpenSlide, and vips, local installation may be hard to get fully working. The local deployment scripts assume a reasonably plain instance of Ubuntu 16.04.


sudo apt-get update
sudo apt-get install -y --force-yes libssl-dev git python2.7-dev python-pip
sudo pip install -U pip
sudo pip install -U 'ansible<2.5'
git clone


cd HistomicsTK/ansible

Note that if there are network issues, this deployment script does not automatically retry installation. It may be necessary to delete partial files and run it again.

Installing Slice CLI Docker Images for Analysis

One of the primary uses of HistomicsTK as a Girder plugin is to analyze images. Analyses are configured using Docker images conforming to the Slicer execution model. Different analysis Docker images can be installed by a system administrator using the Web API (the link is on the bottom of the Girder web page).

Selecting the Web API will show a list of API endpoints for Girder. In the PUT /HistomicsTK/HistomicsTK/docker_image endpoint, you can add a list of Docker images, such as ["dsarchive/histomicstk:latest"], and then click “Try it out”. This will pull the specified Docker image and make it available to the HistomicsTK interface. You could also use a specific tag (version) from Docker instead of the latest tag. Multiple versions and multiple images can be installed so that they can be compared against each other.

For an example of how to make a Docker image with a Slicer CLI-compatible interface, see here.