Installation#

PlayMolecule is one pip install away. The package itself is small; what you also need is a registry of apps to call (a Docker registry, an HTTP backend, or a local on-disk install) and a container runtime to execute them.

This page covers the end-user setup. If you’re rolling PlayMolecule out for a multi-user cluster, see Install apps for a cluster.

1. Install the Python package#

pip install playmolecule

The package requires Python 3.10+. For an isolated environment, create one with venv, conda, or uv first:

python -m venv .venv
source .venv/bin/activate
pip install playmolecule

2. Pick a container runtime#

PlayMolecule apps run as containers. Set PM_RUNTIME to one of:

Runtime	When to use
`docker`	Default. You have Docker installed and your user can run `docker` without `sudo`.
`apptainer`	HPC / shared cluster nodes where Docker isn’t available.

export PM_RUNTIME=docker     # or apptainer

See Switch between Docker and Apptainer for the practical differences.

3. Choose a registry#

The registry is where PlayMolecule finds apps. By default, PlayMolecule points at Acellera’s GCloud-hosted Docker registry:

docker://europe-southwest1-docker.pkg.dev/repositories-368911

You authenticate to that registry the same way you would for any private Docker registry, usually with gcloud auth configure-docker. Acellera provides a service-account JSON to customers; see Install apps for a cluster for the full handshake.

To override the default registry set PM_REGISTRIES:

export PM_REGISTRIES=http://playmolecule.example.com  # remote HTTP backend
export PM_REGISTRIES=local:/path/to/my-apps           # developer use: iterate on your own app manifests on disk

See Environment variables for the full list of PM_* settings.

4. (Optional) Log in to a remote backend#

If your PM_REGISTRIES is an http:// URL, you also need to authenticate before running jobs:

playmolecule login --email you@example.com

This stores a cookie under ~/.cache/playmolecule/cookies/ and is reused on every subsequent call. See Log in to the HTTP backend.

5. Verify#

from playmolecule import describe_apps

describe_apps()

You should see a list of available apps and a one-line description for each. If the list is empty, the registry is either unreachable or empty. Check that PM_REGISTRIES points where you expect and that you can docker pull an image from it manually.

Licensing#

The playmolecule Python package on PyPI is free to install. The apps it runs (ProteinPrepare, DeepSite, Parameterize, and the rest of Acellera’s container catalogue) are commercial software and require an Acellera licence to execute. Without a valid licence file (or floating-licence server), the containers will refuse to run.

PlayMolecule® is a virtual environment for drug discovery where simulations, AI, and data are integrated to uncover new insights. Contact Acellera to book a demo and obtain a quote tailored to your needs.

Contributors: working from a checkout#

If you’re developing PlayMolecule itself, uv is the recommended tool:

uv sync --group dev      # install dev + test deps
uv sync --group docs     # add doc-build deps
uv run pytest            # run the test suite

See the [dependency-groups] table in pyproject.toml for the full list of optional groups.