# Update installed apps

## Goal

Refresh the locally cached container images (and, for `local:` registries, the on-disk app payloads) so installed apps match what's published in the registry.

## Minimal example

```python
from playmolecule import update_apps

update_apps()
```

Pulls newer versions of every image that's already cached locally, and re-syncs any local registry's `acellera-protocols.zip` if needed.

## Pull every app, including ones you've never used

By default {py:func}`~playmolecule.update_apps` only updates images that are already in the local Docker / SIF cache. Pull everything published in the registry:

```python
update_apps(pull_new=True)
```

Useful right after installing PlayMolecule on a new machine if you want all apps available offline.

## Pick interactively

```python
update_apps(interactive=True)
```

Prints a numbered table of every available app with `✓ Installed` / `✗ Not installed` markers, then prompts:

```text
Options:
  - Enter numbers separated by spaces to select specific apps (e.g., '1 3 5')
  - Enter 'all' to select all apps
  - Enter 'installed' to select only installed apps
  - Enter 'new' to select only non-installed apps
  - Press Enter to cancel
```

`interactive=True` implies `pull_new=True`.

## Pass a service-account JSON (for `local:` registries)

If your `PM_REGISTRIES` includes a `local:` URI backed by Acellera-provided GCS payloads, point at the service-account JSON Acellera issued you:

```python
update_apps(service_acc_json="/etc/playmolecule/sa.json")
```

For pure `docker://` registries the JSON is not needed — Docker handles auth via `gcloud auth configure-docker`.

## Combine forms

```python
# Pull every app and reauth GCS with a service account in one call
update_apps(service_acc_json="/etc/playmolecule/sa.json", pull_new=True)
```

## When to run it

- After Acellera notifies you of a new release.
- After installing PlayMolecule on a new node and you want every app available without waiting for first-use pull.
- As a recurring cron job on a shared install (paired with [`PM_REGISTRIES=local:/opt/playmolecule`](install-apps-for-a-cluster.md) so every user benefits without each running update themselves).

## Gotchas

- Updating an image may change its parameters or output names. Pin versions in scripts (see [Select an app version](select-an-app-version.md)) before running `update_apps` against a production install.
- The function logs progress per image. For 30+ apps the output is long; redirect to a log file in cron use.
- `update_apps()` does not delete obsolete images. Reclaim space with `docker image prune` (Docker) or by removing old `*.sif` files from `PM_SIF_CACHE_DIR` (Apptainer).

## See also

- {py:func}`~playmolecule.update_apps`
- [Install apps for a cluster](install-apps-for-a-cluster.md)
- [Select an app version](select-an-app-version.md)