Installation¶

Using Docker¶

Docker is the recommended method for installing and running HistoQC. Containerized runtimes like Docker are more portable and avoid issues with Python environment management, and ensure reproducible application behavior. Docker is available for Windows, MacOS, and Linux.

Note

These instructions assume you have Docker installed on your system. Docker installation instructions.

Run the official HistoQC Docker image from Docker Hub:

docker run -v <local-path>:/data --name <container-name> -p <local-port>:5000 -it histotools/histoqc:master /bin/bash
# Example:
# docker run -v /local/datadir:/data --name my_container -p 5000:5000 -it histotools/histoqc:master /bin/bash

Your terminal will open a bash shell inside the Docker container. You can now proceed to run HistoQC commands. See Running HistoQC

Using pip¶

While we recommend using Docker for most users, some may prefer installing HistoQC from source for development or customization purposes.

Follow these steps to install and set up HistoQC:

Clone the Repository

Clone the HistoQC repository to your local machine:
```
git clone https://github.com/choosehappy/HistoQC.git
cd HistoQC
```
(Optional) Set Up a Virtual Environment

It is recommended to use a virtual environment to manage dependencies:
```
python3 -m venv venv
source venv/bin/activate
```
Install HistoQC
```
pip install .
```
Verify Installation

Run the following command to verify that HistoQC is installed correctly:
```
histoqc --help
```
This should display the CLI usage instructions.