Skip to content

Getting started

Testing KGTK with MyBinder

The easiest, no-cost way of trying out KGTK is through MyBinder. We have made available several example notebooks to show some of the features of KGTK, which can be run in two environments:

  • Basic KGTK functionality: This notebook may take 5-10 minutes to launch, please be patient. Note that in this notebook some KGTK commands (graph analytics and embeddings) will not run. To launch the notebook in your browser, click on the "Binder" icon: Binder

  • Advanced KGTK functionality: This notebook may take 10-20 minutes to launch. It includes basic KGTK functionality and graph analytics and embedding capabilities of KGTK: Binder

For executing KGTK with large datasets, we recommend a Docker/local installation.

Using KGTK with Docker

If you have Docker installed, we have prepared a Docker image with KGTK:

docker pull uscisii2/kgtk

To run KGTK in the command line type:

docker run -it --rm  --user root -e NB_GID=100 -e GEN_CERT=yes -e GRANT_SUDO=yes uscisii2/kgtk:latest /bin/bash

Note: if you want to load data from your local machine, you will need to mount a volume. For example, to mount the current directory ($PWD) and launch KGTK in command line mode:

docker run -it --rm -v $PWD:/out --user root -e NB_GID=100 -e GEN_CERT=yes -e GRANT_SUDO=yes uscisii2/kgtk:latest /bin/bash

If you want to run KGTK in a Jupyter notebook, mounting the current directory ($PWD) as a folder called /out then you will have to type:

docker run -it -v $PWD:/out -p 8888:8888 uscisii2/kgtk:latest /bin/bash -c "jupyter notebook --ip='*' --port=8888 --no-browser"

You will see a message similar to:

[C 22:36:40.418 NotebookApp]

    To access the notebook, open this file in a browser:
    Or copy and paste one of these URLs:

Copy the localhost URL (in the case above, this is random every time) and paste it in your browser. In order to run KGTK commands in a notebook, remember to add %%bash in the line before your command, as shown below:

kgtk --help

As a result, now you should be able to see a help message similar to the one depicted below:



if you want to load data from your local machine or save the results obtained with KGTK, you will need to mount a volume as described above. Notebooks stored inside the container will be erased after the container finishes its execution.


Older versions of KGTK (0.3.2 and 0.2.1) require --allow-root as part of the jupyter notebook command jupyter notebook --ip='*' --port=8888 --allow-root --no-browser

More information about all available versions and tags is available here: For example, the dev branch is available at uscisii2/kgtk:latest-dev.

Installing KGTK from pip

Before you start: Our installation will use a conda environment. If you don't have a conda installed, follow this link to install it.

  1. Set up your own conda environment:
conda create -n kgtk-env python=3.7
conda activate kgtk-env

Note: Installing Graph-tool is problematic on python 3.8 and out of a virtual environment. Thus: the advised installation path is by using a virtual environment.

  1. Install: pip install kgtk

You can test if kgtk is installed properly now with: kgtk -h.

  1. Install graph-tool: conda install -c conda-forge graph-tool. If you don't use conda or run into problems, see these instructions.

Updating your KGTK installation

To update your version of KGTK, just follow the instructions below:

  • If you installed KGTK with through Docker, then just pull the most recent image: docker pull <image_name>, where <image_name> is the tag of the image of interest (e.g. uscisii2/kgtk:latest)
  • If you installed KGTK from pip, then type pip install -U kgtk.
  • If you installed KGTK from GitHub, then type git pull && pip install . Alternatively, you may execute: git pull && python install.
  • If you installed KGTK in development mode, (i.e., pip install -e); then you only need to do update your repository: git pull.

Running KGTK commands

To list all the available KGTK commands, run:

kgtk -h

To see the arguments of a particular commands, run:

kgtk <command> -h

An example command that computes instances of the subclasses of two classes:

kgtk instances --transitive --class Q13442814,Q12345678