Install the FABRIC Python API

Most users will start using FABRIC via our pre-configured JupyterHub environment. However, advanced users might want to install the Python API on their laptop or a server. This article describes how to install the FABRIC Python API on your machine and use it in standard Python applications or even by running Jupyter notebooks locally.

This example shows how install the FABRIC API and run the Jupyter example suite in a Python virtual environment on your local machine.

The FABRIC API is available in the following github repo


  • Python 3.9

IMPORTANT: Using a Python version less than 3.9 is the most common issue that prevents users from successfully deploying the FABRIC API locally.


Check your Python3 version. If it is less than 3.9 you need to upgrade.

bash-3.2$ python3 --version 
Python 3.9.2

Use pip3 to install the python virtual environment software

bash-3.2$ pip3 install virtualenv virtualenvwrapper

Start a python virtual environment to contain your experiments

bash-3.2$ virtualenv fabric-jupyter
created virtual environment in 551ms
  creator CPython3Posix(dest=/Users/pruth/git/fabric-jupyter, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/pruth/Library/Application Support/virtualenv)
    added seed packages: pip==21.2.3, setuptools==57.4.0, wheel==0.37.0
  activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator
bash-3.2$ source fabric-jupyter/bin/activate
(fabric-jupyter) bash-3.2$ 

Install the FABRIC testbed CLI/API

(fabric-jupyter) bash-3.2$ pip3 install fabrictestbed

Configure the Environment

Set the environment variables to point to the the FABRIC Credential Manager and Orchestrator hosts

(fabric-jupyter) bash-3.2$ export
(fabric-jupyter) bash-3.2$ export

Use the portal to Generate a FABRIC token.

Click “Sign up” in the portal.

To generate a new token, click “Create Token”

Click “Create Token”

You new token has been created. Download or cut/paste your new token to a file in a known location on your local machine.

Download or cut/paste the json file that includes your new token. Put this file in a known location on your local machine.

This token is valid for 24 hours. If you want to use FABRIC tomorrow you will need to generate another token.

Save the token in a file on the local machine. Do not remove the json information in the file. Set the environment variable to point to the json file containing your new token.

(fabric-jupyter) bash-3.2$ export FABRIC_TOKEN_LOCATION=/Users/pruth/.fabric_token.json

At this point your environment is ready to run an application using the FABRIC API. If you have an existing FABRIC application you can run it now and skip the rest of this article. If you want to use FABRIC via a local Jupyter notebook continue reading.

Install Jupyter in the Virtual Environment

Install Jupyter in the virtual environment using pip3.

(fabric-jupyter) bash-3.2$ pip3 install jupyter

Run the FABRIC Jupyter-examples Notebook Suite

Clone the github repo that include the example notebooks.

(fabric-jupyter) bash-3.2$ git clone

Many of the examples use paramiko to access your FABRIC slices via ssh. Optionally, install paramiko if you want use in notebooks that require it.

(fabric-jupyter) bash-3.2$ pip3 install paramiko

Some of the examples use bash. You can install the Jupyter bash kernel if you want to use these notebooks.

(fabric-jupyter) bash-3.2$ pip3 install bash_kernel
(fabric-jupyter) bash-3.2$ python -m bash_kernel.install

Run the FABRIC table of contents notebook.

(fabric-jupyter) bash-3.2$ jupyter-notebook jupyter-examples/start_here.ipynb 

This should load the notebook in a new browser tab. You can now click any notebook to open it in another browser tab.

Start running the example notebooks locally.

Trouble Shooting

Error: No module named ‘fabrictestbed’

Upgrading to Python 3.9 occasionally causes errors when importing the FABRIC Python modules. If you see the following error when trying to import the fabrictestbed module the solution is below.

No module named ‘fabrictestbed’

This might have been caused by installing Jupyter when another version of Python was set as the default. Check the Jupyter kernel config file here: /usr/local/share/jupyter/kernels/python3/kernel.json. Edit the Python path to lead to python3.9

 "argv": [
 "display_name": "Python 3 (ipykernel)",
 "language": "python",
 "metadata": {
  "debugger": true
Updated on November 22, 2022

Was this article helpful?

Related Articles

Need Help?
Can't find the answer you're looking for? Search and ask questions in the forum!


  1. I have set this up and have the hello_fabric notebook running.
    When I get to Line 11 to create the slice manager object, I get the error KeyError: ‘CILOGON_REFRESH_TOKEN’
    I have downloaded the token from the portal and set the env vars. I am logged in and have the FabricPortal open as well. Am I missing a step?
    Note I am using a conda env instead of virtualenv.

    1. Are you using a token from the beta portal and using the beta services? These instructions are for the production portal and services. For now, only the beta services are available. You will need to replace the production references to beta for the portal and all services.

      1. I was using the beta portal, but did not have the beta settings for the FABRIC_CREDMGR_HOST and FABRIC_ORCHESTRATOR_HOST env exports.
        Also of note the FABRIC_TOKEN_LOCATION has to be absolute, relative does not work.

        1. I had the same issue before but later I figured these host could be found via beta jupyterhub – “fabric_examples” – “start_here” – “hello_fabric” – step #3

Leave a Comment