Installation

CADDForge packages require Python 3.10 or newer.

Choose the smallest environment for your task

For the introductory table tutorial, core plus caddforge-datascience is sufficient; no molecular simulation environment is needed. For the generic pipeline tutorial, core alone is sufficient. Scientific plugin extras do not install every external engine, GPU driver, or prepared input dataset.

Component	Declared Python support	Validation / runtime scope
Core and docs	Python 3.10+	Package CI targets Linux/Python 3.10 and 3.12; local documentation checks also use 3.13
Full bundle	Check each pinned component	Release CI targets Linux/Python 3.10 and 3.12; validation of the updated public pins remains pending
Scientific tools	Check plugin and engine requirements	External binaries, platform/GPU support, and conda stacks vary; this is not a claim of universal support

Install conda-managed scientific stacks first

If a plugin recommends installing scientific dependencies with conda, install those conda packages before installing any pip packages, including caddforge.

Recommended order:

conda create -n caddforge python=3.10
conda activate caddforge

# Install heavy scientific/runtime packages first.
conda install -c conda-forge openfe openff-toolkit rdkit pdbfixer openmm

# Install published CADDForge components after the conda environment is complete.
python -m pip install caddforge-core==0.22.0 caddforge-fep==0.7.0

Installing conda packages after pip packages have already populated the environment can replace or downgrade shared dependencies and leave the environment inconsistent. When in doubt, create a fresh environment and install the conda-managed stack first.

For Slurm jobs, the compute node also needs access to this environment. See the Slurm backend guide for packed-environment and wheelhouse options.

Install CADDForge packages

The updated public bundle is still awaiting its docs release, final component pins, and full installation validation. Install published components individually for now; the version matrix records availability. After that bundle release, this command installs the complete toolbox, including GUI integrations, MD minimization, ML UI dependencies, and installed documentation:

python -m pip install caddforge

The metadata-only caddforge bundle installs no modules or commands itself. Its copied metadata retains baseline 0.22.1 and pins core 0.21.0, data science 0.4.0, descriptors 0.10.1, docking 0.6.1, FEP 0.6.0, GUI 0.5.0, MD 0.12.1, ML 0.3.0, QM 0.2.1, and docs 0.2.1 for local validation. These inherited pins do not identify releases of the edited public sources. New public component versions are tagged; the bundle pins must be updated and tested with the docs 0.3.0 before bundle publication. Documentation authoring and test extras are excluded from the runtime bundle.

For core alone or selected plugins:

python -m pip install caddforge-core==0.22.0
python -m pip install caddforge-qm==0.3.0

Plugins depend directly on caddforge-core and install it automatically. Python imports remain caddforge and CLI commands remain caddforge ....

The versions in the selective-install examples above are published on PyPI. MD 0.13.0 is tagged and awaiting publication as of 2026-10-15; use its tagged source checkout until it is available on the index. Full-bundle release validation targets Linux on Python 3.10 and 3.12. Installing Python plugins does not install external scientific engines.

The bundle's 0.x series remains initial development: its public API and supported component set may change. Version 1.0.0 is reserved for a future stable API commitment. The version matrix records tags and publication status.

The core package includes conda-pack as a dependency. This provides caddforge pack-env, which creates managed Slurm environment archives and checksum sidecars without a separate conda-pack installation step.

For editable installs from checkouts containing the public tags, select the versions in the version matrix and install without version overrides:

git -C ../caddforge-core switch --detach v0.22.0
python -m pip install -e ../caddforge-core
git -C ../caddforge-docking switch --detach v0.7.0
python -m pip install -e "../caddforge-docking[gui]"

For MD before its index publication, use a checkout containing v0.13.0:

git -C ../caddforge-md switch --detach v0.13.0
python -m pip install -e ../caddforge-md

Published artifacts must use their actual public release versions. Temporary VCS version overrides are only for local validation, never for publishing.

After installation, verify plugin discovery:

caddforge list-tools

External software

Some plugins call external scientific software that is not installed by the Python package. Examples include docking engines, QM programs, and MD engines. Check the plugin pages for tool-specific runtime requirements.

PyOCL and Java

QM, descriptors, and docking install the public pyocl-idor>=0.8.3 distribution. MD can use it through those plugins, and the complete bundle includes it indirectly. The Python import package remains pyocl.

Install Java 21 or newer and point JAVA_HOME to that installation. The affected GitHub workflows already provision Java 21. To check the Python package and JVM in the same environment:

python -m pip show pyocl-idor
java -version
python -c "import pyocl; print(pyocl.__version__)"

A JVM lookup or class-version error indicates a missing, misconfigured, or older Java runtime; see troubleshooting.

Documentation package

The planned bundle includes docs automatically. Documentation 0.3.0 is tagged; its package-index publication is pending. Until then, install the source checkout with python -m pip install ../caddforge-docs. Once its public release is available, core-only and selective plugin installations can install it separately:

python -m pip install caddforge-docs
caddforge docs

After installing a bundle that includes docs, run caddforge docs directly.

Installing this package enables the optional docs command on core 0.21.0 or later. It opens the documentation shipped with the installed docs release and serves until Ctrl+C. The built site works without internet access or documentation build tools. Use --host and --port to choose the listening address, or --no-browser to open the printed URL manually. See the CLI reference.

GUI extras

The planned complete bundle includes GUI extras. For selective installations, install the plugin's GUI extra. Docking and FEP are published; the MD command requires its tagged release to be available on the index:

python -m pip install "caddforge-docking[gui]"
python -m pip install "caddforge-md[gui]"
python -m pip install "caddforge-fep[gui]"

Migrating an existing installation

Prefer a fresh environment. To migrate the former core distribution in place, install the renamed core and upgrade every retained plugin to its public release. The example below retains docking and QM; adapt that list to your environment:

python -m pip uninstall caddforge
python -m pip install --upgrade caddforge-core caddforge-docking caddforge-qm
python -m pip check
caddforge list-tools

For a minimal installation, install caddforge-core instead and upgrade every retained plugin to its migrated release. Keep older plugin releases in their original environments: they depend on the legacy caddforge core distribution. Do not install both old and renamed core distributions, because they own the same Python files. If both were installed, remove the old caddforge distribution and force-reinstall caddforge-core afterwards.

importlib.metadata.version("caddforge-core") reports the runtime version; version("caddforge") reports the optional bundle version. MD provenance distinguishes both. Historical configuration, registry, result, and provenance records remain readable. Uninstalling the new bundle does not uninstall its dependencies.