Quickstart Guide

Installation

It should be possible to install MolCube-API Client with the following software pre-installed:

python (>=3.12)
pip
cairo / libcairo

These instructions assume you already have python and pip installed.

Please ensure your pip version is up-to-date, as it has been reported that some older versions are unable to install MolCube-API Client:

pip install -U pip

On-Premise installations

If you are an OnPrem user, this API is built for CubeBuilder 2026.1.1. Please check the OnPrem User Guide to verify your installation version.

Prerequisite: Cairo

MolCube’s client makes use of the cairo development library, which cannot be installed by pip. Instead, you will either need to use a package manager or install it from source. Some suggested methods are detailed below.

The easiest way is usually Conda. If that is not an option, macOS users can try Homebrew, users of Debian-based distributions (such as Ubuntu) should see the Apt instructions below. We do not yet have a recommended procedure for installation via RPM or yum.

If you do not already have a copy of conda, we recommend installing the Miniforge distribution here, since it is lightweight, has a relatively straightforward installation process, and is pre-configured to use the conda-forge repository by default.

To install in a clean environment named molcube, use the procedure below:

conda create -n molcube -c conda-forge 'python>=3.12 ' pycairo
conda activate molcube

Then, proceed to the instructions below. Note that MolCube-API Client is not available from any Conda channel, so it must be installed with pip.

This is the recommended installation method for macOS users who are not using Conda.

First, ensure the Python distribution you are using was installed by Homebrew:

which python  # or python3
which pip     # or pip3

The output should look something like this:

$ which python
/opt/homebrew/bin/python
$ which pip
/opt/homebrew/bin/pip

If it does not, then you either did not install Python through homebrew or another Python executable is earlier in your PATH environment.

Assuming your Python installation is from Homebrew, you can then do the following:

brew install cairo pkgconf
pip install -U pip && pip install -U pycairo

Then, proceed to the instructions below.

First, ensure that your Python distribution is the system’s Python:

which python  # or python3
which pip     # or pip3

The output should look something like this (exact paths may differ):

$ which python  # or python3
/usr/bin/python
$ which pip     # or pip3
/usr/bin/pip

Alternatively, you may see /usr/local/bin/python, etc. It should NOT reference conda, miniforge, miniconda, or any other package manager. If it does, then that Python version is probably earlier in your PATH environment.

Assuming your Python installation is the system’s, use the following procedure to install the prerequisites:

apt update && apt upgrade -y && \
   apt install -y build-essential libcairo2-dev pkg-config && \
   pip install -U pip

Install MolCube Client

Assuming you have obtained the above dependencies, then the following command should be enough:

pip install -U http://deployments.molcube.com/api/molcube-0.4.2-py3-none-any.whl

You can check whether installation was successful like so:

python -c 'import molcube; print(molcube.__version__)'

Expected output: 0.4.2. If you get any other message, something probably went wrong.

Troubleshooting

See below for some common issues.

ModuleNotFoundError

If you see the message ModuleNotFoundError: No module named 'molcube' despite getting no errors after running the pip install commands above, verify that your are using the same environment as you used for installation. E.g., if you used conda and created an environment named molcube, then you first need to activate the molcube environment:

$ conda activate molcube
$ python -c 'import molcube; print(molcube.__version__)'
0.4.2

Obtain API key

To retrieve the API key for a user, there are two methods available:

Case 1: Generate API key programmatically

Use your MolCube-Builder account credentials (username and password) to generate an API key via generate_api_key() method. Use the generated API key for authentication.

Case 2: Generate API key from web application

Log in to the MolCube-Builder web application and navigate to the Profile page. Generate an API key and copy the key value. Use the copied API key for authentication.

Additional Notes

The API key does not have an expiration time, but only one can be active at a time.

If a new API key is generated using either method, the previous API key will be invalidated and can no longer be used. For security reasons, remember to store your API key securely and never commit it to version control.

If you suspect that your API key has been compromised, then you should regenerate it as soon as possible.

Authenticate API Client

For On-Premise (>= v2025.2.5) Users:

molcube = mc.API('localhost', 8000, is_onprem=True)

For other users:

# Initialize MolCube API client
molcube = mc.API('api.molcube.com', 443)

# Case 1: Generate API key with username and password, then authenticate
# username = "your_username"
# password = "your_password"
# api_key = molcube.generate_api_key(username=username, password=password)
# molcube.authenticate(api_token=api_key)

# Case 2: Authenticate with an existing API key
api_access_key = "your_api_key"
molcube.authenticate(api_token=api_access_key)

Minimal project example

This example loads 2hac from disk and uses default options only:

import molcube as mc
from pprint import pprint

molcube = mc.API('api.molcube.com', 443)
molcube.authenticate(api_token=api_access_key)

# simplest possible case: use defaults for everything
pdbreader = molcube.create_pdb_reader_project()
pdbreader.create_project(title='test-defaults', ff='charmmff', customPdb='files/2hac.cif')
pdbreader.set_defaults()

# if modifying chain selection, do so here
assert pdbreader.confirm_chains()

# if modifying manipulation options, do so here
assert pdbreader.model_pdb()

For more detailed examples, see User Guide.