OpenHI Installation and Usage

To use OpenHI web interface, you need to install all necessary dependencies, OpenHI library, configure the framework to your need and run the web server. Only after that you can visit the framework by web browser of your choice.


This installation guide includes all steps from installing required dependencies up to installing OpenHI. There are some libraries used by OpenHI that requires additional installation (outside PyPI), including:

  1. OpenSlide

  2. libMI and MMSI

  3. (For macOS and Windows) Pyvips

For Python dependencies, we will do that using pip.

pip install -r requirements.txt

After that, we build the MySQL table using script in the sql folder of legacy the legacy module (module/legacy/mysql). The current version is data_model_4-1.

Lastly, install OpenHI library itself.

python install


If you are installing for development, OpenHI should be installed in development mode.

python develop

Usage (running the framework)

Before you can successfully run OpenHI you should configure the platform first. This consist of 3 steps: (1) configure the database (MySQL), (2) configure the OpenHI configuration file, and (3) run the main script (

MySQL database configuration

Database version: v4.1

  • Add the MySQL server configuration to the configuration file located in module/legacy/static/data_model_4-1_conf.ini. Noted that this file can be based on the example file located at module/legacy/static/data_model_4-1_conf_example.ini.

  • Run the MySQL script to create the data schema in your MySQL server. Run: module/legacy/static/data_model_4-1.sql

  • Run the Python file to fill the newly created table with the clinical and biospecimen data (xml file) using python script. Run module/legacy/static/

OpenHI framework configuration

The OpenHI has one main external configuration file located at module/legacy/static/OpenHI_conf_example.ini which includes the following configurations.

  • MySQL setting

    • Host and port

    • Authentication (username and password)

    • OpenHI database schema name (include to support different data models)

  • Web framework configuration

    • Host and port [default at port 5000]

    • Running modes

  • WSI

    • Default WSI for newly logged-in annotators.

Run the framework

To run the framework run the main Flask python file which is with the following command.

cd module/legacy/

Try to visit the GUI using a web browser at the specified port. The default port is 5000, so try to visit

You should see the GUI like this.


Legacy installation

To run OpenHIv1. You should follow the legacy installation guideline. OpenHIv1 release can be downloaded from the Release Page