Get started#

Installation#

This page explains the supported environments and shows three ways to install SynPlanner.

Supported environments#

Python: >=3.10,<3.15 (CPython). The publishing workflow builds with Python 3.12.
OS/arch: developed and CI-tested on Linux x86_64 and MacOS arm64. Other platforms may work, but Docker is recommended for maximum portability.

What you get after install#

CLI entrypoint: synplan
Python API: import synplan
Data and weights are not bundled. Fetch them with synplan download_preset --preset synplanner-article --save_to synplan_data or follow Data download.

Install with pip (recommended)#

Use a virtual environment.

pip install SynPlanner

Verify:

synplan --version
synplan --help
python -c "import synplan, sys; print('synplan', synplan.__version__)"

Install with Docker (portable)#

Build and run the CLI inside a container. The provided Dockerfile targets Linux/AMD64.

docker build --platform linux/amd64 -t synplan:latest-cli-amd64 -f cli.Dockerfile .
docker run --rm --platform linux/amd64 -it synplan:latest-cli-amd64 --help

From source with uv (dev)#

git clone https://github.com/Laboratoire-de-Chemoinformatique/SynPlanner.git
cd SynPlanner/
uv sync --extra cpu   # add "--group docs --group dev" if you need docs or dev extras
uv run synplan --help

Limitations and notes#

Wheels are published from Linux. If you experience platform issues on macOS/Windows, prefer Docker or a Linux environment (e.g., WSL2).
Example data and model weights are not included; download them with the CLI (see Data download).
To run the full planning quickstart in 10 minutes, continue to 10 minutes to SynPlanner.

Data download#

Use the built-in downloader to fetch pre-trained models, reaction rules, and building blocks from HuggingFace.

Preset download (recommended)#

Download a ready-to-use preset with all components needed for retrosynthetic planning:

synplan download_preset --preset synplanner-article --save_to synplan_data

This downloads the synplanner-article preset, which includes:

Reaction rules (TSV): policy/supervised_gcn/v1/reaction_rules.tsv
Ranking policy weights: policy/supervised_gcn/v1/v1/ranking_policy.ckpt
Filtering policy weights: policy/supervised_gcn/v1/v1/filtering_policy.ckpt
Value network weights: value/supervised_gcn/v1/value_network.ckpt
Building blocks: building_blocks/emolecules-salt-ln/building_blocks.tsv

Python API:

from synplan.utils.loading import download_preset

paths = download_preset("synplanner-article", save_to="synplan_data")
rules_path = paths["reaction_rules"]
policy_path = paths["ranking_policy"]
bb_path = paths["building_blocks"]

Details#

For a full list of datasets and descriptions, see Data.

Use prebuilt Docker images#

Prebuilt images are published to GitHub Container Registry (GHCR) for the Linux/AMD64 platform.

Registry and tags#

Registry path: ghcr.io/laboratoire-de-chemoinformatique/synplanner
Tag pattern: <version>-cli-amd64 or <version>-gui-amd64

Set your version once (replace with an existing tag if needed):

VERSION=1.3.2

Pull images#

# CLI image
docker pull ghcr.io/laboratoire-de-chemoinformatique/synplanner:${VERSION}-cli-amd64

# GUI image
docker pull ghcr.io/laboratoire-de-chemoinformatique/synplanner:${VERSION}-gui-amd64

Run the CLI#

Show help:

docker run --rm --platform linux/amd64 \
  ghcr.io/laboratoire-de-chemoinformatique/synplanner:${VERSION}-cli-amd64 --help

Quick planning example (mount config and data):

docker run --rm --platform linux/amd64 \
  -v "$(pwd)":/app -w /app \
  ghcr.io/laboratoire-de-chemoinformatique/synplanner:${VERSION}-cli-amd64 \
  planning \
    --config configs/planning.yaml \
    --targets tutorials/synplan_data/benchmarks/sascore/targets_with_sascore_1.5_2.5.smi \
    --reaction_rules synplan_data/policy/supervised_gcn/v1/reaction_rules.tsv \
    --building_blocks synplan_data/building_blocks/emolecules-salt-ln/building_blocks.tsv \
    --policy_network synplan_data/policy/supervised_gcn/v1/v1/ranking_policy.ckpt \
    --results_dir planning_results

Run the GUI#

Expose port 8501 on the host and open your browser at http://localhost:8501:

docker run --rm --platform linux/amd64 -p 8501:8501 \
  ghcr.io/laboratoire-de-chemoinformatique/synplanner:${VERSION}-gui-amd64

Notes#

The repository path is lowercased for Docker compatibility.
Images are built for linux/amd64; running on arm64 hosts may require emulation (e.g. Docker Desktop with Rosetta/qemu).
For data download instructions, see Data download.

Run in Google Colab#

Run selected tutorials directly in Google Colab (no local install):

Retrosynthetic planning
SynPlanner benchmarking
Route clustering by strategic bonds