Foundry: one installation for RFD3, RF3 and ProteinMPNN protein design models

A distribution for design, inverse folding and folding

Foundry provides tooling and infrastructure for using and training all classes of models for protein design. The repository description calls it a central repository for biomolecular foundation models with shared trainers and pipeline components, and the README puts it more concretely: it covers design with RFD3, inverse folding with ProteinMPNN, and protein folding with RF3.

That trio is the reason the project exists. These models were developed separately, they each have their own dependencies, their own checkpoint formats and their own runtime requirements, and running two of them in the same environment was historically an exercise in dependency conflict resolution. Foundry's contribution is to package them together while keeping the model-specific parts separate.

The stated unifying layer is AtomWorks, described as a unified framework for manipulating and processing biomolecular structures, and the README says all models within Foundry rely on it for both training and inference. Structure I/O and featurization continue to use AtomWorks 3, which is a sensible place to standardise, since every one of these models consumes a structure and represents it as tensors.

The audience is a structural biologist or ML engineer running protein design pipelines. A separate module, RFO, combines RF3 gradient-guided sequence optimization with Boltz-2 structure prediction and external ProteinMPNN or LigandMPNN sequence redesign, and its guide points to separate MPNN installation instructions, which tells you the components are still separable when a workflow needs them to be.

The 1.0.0 refactor deleted the shared foundry package

The most consequential paragraph in the README is a breaking change notice, and it is worth reading before anything else.

Foundry 1.0.0 ships the tools in one rc-foundry distribution. Each tool owns its runtime infrastructure under models/<tool>/src/<tool>/_core/, and model checkpoint registries live in <tool>/checkpoints.py. The shared `foundry` Python package has been removed. Custom Python imports and Hydra `_target_` paths must use the corresponding tool's namespace, and the documentation gives the exact transformation: foundry.utils.torch becomes rfd3._core.utils.torch for RFD3.

If you have a project with its own Hydra configuration files pointing at `foundry.*` targets, those files break on upgrade until you rewrite them. That is a real cost, and it is the kind of change that a project should either make in one step or not at all.

Two things are deliberately preserved. Existing released checkpoints are translated when loaded, and the weights are unchanged, so model files are not invalidated by the refactor. The foundry checkpoint CLI, the model CLIs, the checkpoint locations and the FOUNDRY_* environment variables are all retained, and the numerical settings, including RFD3's fast and legacy modes, are unchanged by the refactor.

The practical summary is that the public entry points survived, the internal import paths did not, and the checkpoints are portable across the boundary.

Installing on Linux, on Intel XPU and on Apple Silicon

The standard install is one command.

pip install "rc-foundry[all]"

The `all` extra pulls in the optional dependency groups for every model, including the RF3 extras and the RFO extras. The package requires Python 3.12 or later.

Intel XPU devices need PyTorch with XPU support installed first, and then Foundry.

pip install torch --index-url https://download.pytorch.org/whl/xpu
pip install "rc-foundry[all]"

The README includes a warning here that is easy to miss: use pip and not uv for XPU installs, because uv re-resolves dependencies and may replace your XPU torch with the standard PyPI version. That is a dependency resolver fighting the hardware, and the documented workaround is to keep the standard installer for that case.

macOS on Apple Silicon is a third path, and it involves a community fork rather than the published package.

pip install torch
pip install "rc-foundry[all] @ git+https://github.com/fnachon/foundry.git"

MPS support is available through that fork. All three models, RFD3, RF3 and ProteinMPNN/LigandMPNN, run on Apple Silicon MPS, according to the README. The fork is a dependency you are taking on trust, and the README does not say how it differs from the published distribution beyond the MPS support.

Checkpoints live in ~/.foundry and are found through an env var

Model weights are handled by a small command line interface, and the design is straightforward enough to describe in full.

foundry install base-models --checkpoint-dir <path/to/ckpt/dir>

Without an explicit path, the checkpoint directory defaults to ~/.foundry/checkpoints. The `base-models` target installs the latest RFD3, RF3 and MPNN variants. The documentation also notes that you can download all supported models, including multiple checkpoints of RF3, with `all`, or list the models sequentially, for example `foundry install rfd3 rf3 ...`.

Two more commands answer the questions you will actually ask in practice.

foundry list-available

lists the registry of available checkpoints, and

foundry list-installed

checks what you already have downloaded. That second one searches ~/.foundry/checkpoints plus $FOUNDRY_CHECKPOINT_DIRS if it is set.

That environment variable is the mechanism for shared or non standard checkpoint locations. The README says Foundry always searches ~/.foundry/checkpoints plus any colon-separated entries in $FOUNDRY_CHECKPOINT_DIRS during inference or subsequent commands to find checkpoints. The separator is a colon, which is the Unix convention, and it is worth noting that the path separator in the variable is Unix style even though the project metadata lists Windows as a supported operating system.

The end-to-end usage examples are in examples/all.ipynb, and the repository also ships examples/enzymes.ipynb and examples/ipd_design_pipeline_collab.ipynb.

The Apple Silicon path is inference only, and float32 only

The macOS support has clear limits, and the README lists them as notes rather than burying them.

The `rf3` extra, which brings in cuEquivariance, is Linux-only and is automatically skipped on macOS. So on an Apple Silicon machine, the RF3 path runs without that acceleration.

Precision is constrained too. Use float32, because bfloat16 is not supported on MPS. The README adds that the MPS accelerator is selected and float32 precision enforced automatically, so the constraint is applied for you rather than left as a silent numerical difference.

Multi-GPU training is not supported on MPS. The macOS path is inference only, which is a reasonable boundary given that MPS is a consumer accelerator, but it means the README's claim that all three models run on Apple Silicon means they run, not that you can train them there.

One more practical detail: for `rf3 fold`, pass an absolute path to the input CIF file. Relative paths are not handled as you would expect.

These constraints are only visible because the documentation is specific about them. The general lesson for anyone evaluating the project is that the platform matrix is uneven, and the parts that differ are exactly the parts that matter for performance and for training.

A Docker image, a Colab notebook, and the question of what Foundry replaces

There are two ways to run Foundry without setting up a Python environment.

The first is the official container image, maintained by the Rosetta Commons and published on Docker Hub. The default image comes with the model weights for the available models, and the `slim` tag lets you either use pre-existing weights or download the weights inside the container. The recipe for the image is in foundry/examples/docker, and the README describes it as a blueprint you can copy to build your own images.

The second is Google Colab. An interactive notebook walks through a basic design pipeline with RFD3, MPNN and RF3, and it is linked from the README as the IPD Design Pipeline Tutorial.

The alternative to Foundry is the one the project was assembled to replace: installing each model repository on its own. The difference in approach is not that Foundry adds a new algorithm. It is that Foundry unifies the checkpoint registry, the CLI, the environment variable names and the structure featurization layer, so that a workflow touching a design model, a folding model and an inverse folding model has one installation and one set of conventions instead of three.

The cost of that unification is the dependency set. The package pulls in torch 2.11 or later, lightning, einops, opt_einsum, jaxtyping, beartype, typer, wandb, hydra-core, environs and atomworks with the ml extra, plus per-model extras such as pydantic for RFD3 and RFD3NA and biopython for RFO. That is a large environment, and for one model on one machine it is a poor trade against installing that model directly.

Licence, Python floor and the release history

One thing to check before you build on this is the licence. The repository's licence field says Other, described as a custom licence that GitHub cannot classify, and the LICENSE file is a LICENSE.md at the top level of the repository. The package metadata in pyproject.toml points its license at that same file, while the classifier list includes an OSI Approved BSD License entry. The two statements do not line up, and the file itself is the one to read, because a custom licence can carry terms that a standard identifier would not.

Nothing in this article is legal advice, and the point is simply that the licence identifier GitHub displays is not the one you can rely on for a compliance review.

On the technical side, the package requires Python 3.12 or later, which is a real constraint for a research group still on 3.10 or 3.11. The AtomWorks dependency is pinned to a range of 3.0.1 up to but not including 4, so an AtomWorks major release will not be picked up silently.

The release history shows v0.1.8 on 2025-12-09 and v0.1.9 on 2025-12-21, while the package metadata now reads version 1.0.0 and the README describes a 1.0.0 distribution. The repository is not archived and the last push was on 2026-10-16, and the default branch is named production rather than main, which suggests releases are cut from a branch that is intended to be stable.

The development workflow is documented as well. Development installs use uv, and the CPU regression suite runs with pytest.

uv pip install -e '.[all,dev]'
pytest

A CPU regression suite in a project that is mostly about GPU inference is a sensible choice, since it is the part of the pipeline most likely to be run on every change.

Editorial conclusion

Adopt Foundry if you need more than one of RFD3, RF3 and ProteinMPNN in the same environment, since the shared checkpoint registry, the unified AtomWorks featurization and one pip install are the reason it exists. Do not adopt it for a single model on a single machine, because the dependency set is large and the per-model extras are where the platform constraints bite. Before installing, read the LICENSE.md file directly, since the repository licence is a custom one that GitHub cannot classify, and check that your Python is 3.12 or later.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. RosettaCommons/foundry on GitHub