# 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](howto/install-apps-for-a-cluster.md).

## 1. Install the Python package

```bash
pip install playmolecule
```

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

```bash
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.                          |

```bash
export PM_RUNTIME=docker     # or apptainer
```

See [Switch between Docker and Apptainer](howto/switch-between-docker-and-apptainer.md) 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:

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

You authenticate to that registry the same way you would for any private Docker registry — usually `gcloud auth configure-docker`. Acellera provides a service-account JSON to customers; see [Install apps for a cluster](howto/install-apps-for-a-cluster.md) for the full handshake.

To override the default registry set `PM_REGISTRIES`:

```bash
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](reference/environment-variables.md) 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:

```bash
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](howto/log-in-to-the-http-backend.md).

## 5. Verify

```python
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](https://www.acellera.com/contact-us) to book a demo and obtain a quote tailored to your needs.

## Contributors: working from a checkout

If you're developing PlayMolecule itself, [`uv`](https://docs.astral.sh/uv/) is the recommended tool:

```bash
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.