Install OpenFold3: Complete Deployment Guide (2026)

There are two ways to install OpenFold3, and one of them will save you an afternoon of debugging. The obvious path is pip install openfold3. It works – until you fire off your first prediction and DeepSpeed crashes because CUTLASS_PATH was never set. The better path is the project’s pixi-managed environment, which pre-wires the CUDA and Triton stack so you skip the class of errors that produce most GitHub issues. This guide walks the pixi route in detail, then covers the raw-pip fixes for anyone who can’t use pixi.

OpenFold3 is worth the setup pain. It’s a bitwise reproduction of DeepMind’s AlphaFold3, developed by the AlQuraishi Lab at Columbia and the OpenFold consortium – Apache 2.0, which means you can test it, retrain it, and ship products on top of it. AlphaFold3 allows limited academic use and nothing commercial. As of March 13, 2026, training datasets are now public on the AWS Registry of Open Data, so full reproduction is possible for the first time.

System Requirements for OpenFold3

Hardware is where most deployments die. Here’s the real bar, straight from the install docs.

As of the official install docs (updated 2026), the 32GB VRAM floor is real – not conservative padding. Python 3.10 through 3.13 are supported. The compute capability minimum of 7.0 (V100 or later) isn’t about raw speed: the DS4Sci_EvoformerAttention kernel simply won’t compile below that threshold. No V100, no inference.

Installing OpenFold3 with pixi (recommended)

Pixi is the project’s blessed dependency manager. As of the 2026 release, OpenFold3 ships four pre-configured pixi environments: openfold3-cpu, openfold3-cuda12, openfold3-cuda13, and openfold3-rocm7 for AMD systems. Pick the one that matches your hardware and you’re done.

# Install pixi (one-time, per machine)
curl -fsSL https://pixi.sh/install.sh | sh

# Restart your shell, then clone the repo
git clone https://github.com/aqlaboratory/openfold-3.git
cd openfold-3

# Activate the CUDA 12 environment (most common)
pixi shell -e openfold3-cuda12

# Download model weights and set up inference
setup_openfold

That’s it for the happy path. H100 or newer? Swap in openfold3-cuda13. MI300 or similar? Use openfold3-rocm7. Everything else – kalign, CUTLASS libraries, Triton kernels – comes bundled.

Alternative: raw pip install

If pixi isn’t an option (locked-down HPC, existing conda env you can’t touch), you can go bare. OpenFold3 is fully packaged on PyPI as of the recent release.

python -m venv .venv
source .venv/bin/activate
pip install openfold3
setup_openfold

This will get you a working import. It will not get you a working inference run. Skip to the errors section – you’ll need it.

First-Time Configuration

Before running inference, three environment variables matter. Set them in your shell profile or the pixi env activation script.

# CUDA toolchain
export CUDA_HOME=/usr/local/cuda # or `module load cuda` on HPC

# CUTLASS path (this is the one everybody forgets)
export CUTLASS_PATH=$(python - <<'PY'
import cutlass_library, pathlib
print(pathlib.Path(cutlass_library.__file__).resolve().parent.joinpath("source"))
PY
)

# Optional: custom cache location for model weights
export OPENFOLD_CACHE=/data/openfold3-cache

The OPENFOLD_CACHE variable is a migration trap. As of v0.4.0, setup_openfold no longer creates the $OPENFOLD_CACHE environment variable automatically – anyone who scripted around the old auto-setup will find their pipeline silently writing weights to a default location with no migration note in the main install docs.

Pro tip: Put the CUTLASS_PATH export inside your venv’s activate script (or pixi’s activation.env). Setting it once per shell is fine for testing, but the first time you SSH into your GPU box at 2 AM and get the evoformer_attn error again, you’ll wish you’d baked it in.

Verifying the Install

Two checks. First, confirm the binaries are on PATH:

run_openfold --help
setup_openfold --help

Then run the canonical smoke test using the included ubiquitin example, as described in the OpenFold3 README:

run_openfold predict 
 --query_json=examples/example_inference_inputs/query_ubiquitin.json

Ubiquitin is 76 residues – a small protein deliberately chosen to be fast. On a warmed-up A100 it finishes in a couple of minutes; first-run kernel compilation adds time on top of that. If it hangs on “compiling kernels” for longer than five minutes on that first run, that’s the DS4Sci kernel JIT-compiling and is normal. Same hang on the second run means your CUTLASS setup is broken.

Common Errors and Actual Fixes

These are the three failures you’ll hit. In order of frequency.

1. No such file or directory: '/usr/local/cuda/bin/nvcc'

CUDA_HOME isn’t set, or points to an installation without nvcc. On HPC clusters, module load cuda usually fixes this; on a workstation, export CUDA_HOME=$(dirname $(dirname $(which nvcc))). The official install docs list this exact error.

2. Error: Unable to JIT load the evoformer_attn op

Fix first, then understand why: run the CUTLASS_PATH one-liner from the configuration section above. The cause – CUTLASS_PATH missing or pointing somewhere without the CUTLASS source – is documented in the install docs and tracked across multiple DeepSpeed GitHub issues. Don’t point it at a system CUTLASS install; version compatibility is finicky enough that the python-derived path is the only reliable option.

3. /usr/bin/ld: cannot find -lcurand

Find the library first: find "$CUDA_HOME" -name 'libcurand.so*'. Whatever directory that returns goes into LD_LIBRARY_PATH – typically $CUDA_HOME/targets/x86_64-linux/lib. CUDA math libraries not being on the linker path is the whole issue.

Upgrading, Rollback, and Uninstall

There’s one migration hazard that isn’t in the main install page and will bite anyone upgrading from a pre-0.4.0 install. Per the release notes, model parameters from earlier releases – for example, of3_ft3_v1.pt – are not compatible with openfold3 versions at or after v0.4.0. The failure mode is silent-ish: the model loads, inference runs, results look nothing like what you got last week. If you’ve fine-tuned weights, keep the old venv around.

Upgrade is a normal pip bump:

pip install --upgrade openfold3
setup_openfold --download all-parameters # re-fetch compatible weights

Also worth knowing: as of v0.4.0, OpenFold3 has switched to kalign3 via the kalign-python PyPI package instead of kalign2, and all kalign alignments now use the Python API. If you had a custom kalign2 binary on PATH, it’s no longer being called.

To uninstall cleanly:

pip uninstall openfold3 python-kalign
rm -rf ~/.openfold3 # weights cache
rm -rf $OPENFOLD_CACHE # if you set a custom one
deactivate && rm -rf .venv

What About Apple Silicon or Weaker GPUs?

Short section, because the honest answer is: it’s rough. The official install requires CUDA 12.1 and 32GB VRAM, which rules out most consumer hardware and every Mac. A community fork exists – openfold-3-mlx – that ports the inference path to Apple’s MLX framework. On a base M4 Mac it reports around 33 seconds per sample for small proteins with over 85 pLDDT accuracy. It’s community-maintained, not official, and lags the main repo. Fine for exploration, not for pipelines.

There’s also a real ceiling on the CUDA side. According to UCSF ChimeraX’s OpenFold tool documentation, AlphaFold3 can handle roughly 5,000 tokens on 80GB of GPU memory – OpenFold3 tops out at around 2,500 tokens on the same hardware. If your complexes are large, budget for an H100 or a smaller batch strategy.

FAQ

Can I run OpenFold3 on a single consumer GPU like an RTX 4090?

The 4090 has 24GB – below the 32GB official minimum. Small proteins will run. Anything large will OOM.

What’s the difference between OpenFold3 and OpenFold2?

Different codebases, different GitHub repos. OpenFold2 (aqlaboratory/openfold) reproduces AlphaFold2: proteins only, monomers and multimers. OpenFold3 (aqlaboratory/openfold-3) reproduces AlphaFold3 and adds RNA, DNA, and small-molecule ligand prediction. Weights and configs are not interchangeable – trying to load OF2 weights into OF3 will fail, not silently produce wrong results.

Do I need MSAs, or can I use single-sequence input?

OpenFold3 needs MSAs for good accuracy. The default pipeline hits the ColabFold MSA server over the network, which is fine for occasional predictions but rate-limited. For batch work, generate MSAs locally with JackHMMER or hhblits following the AlphaFold3 protocol – the run_openfold binary accepts pre-computed alignment paths in the query JSON. If you’re running dozens of predictions a day, setting up a local MMseqs2 server is worth the one-time overhead.

Next step: pull down the ubiquitin example, run it once end-to-end, and time it. Once you have a baseline number for your hardware, you’ll know exactly what a full-sized complex will cost – and whether you need to rent an H100 before the real work starts.