Install RFdiffusion for Protein Design AI (2025 Guide)

Two ways to get RFdiffusion running: build the conda environment from source, or pull the official Docker image. The source path is what the README walks you through – it’s also where most users get stuck. Docker skips that whole class of problem. Unless you specifically need to edit the model code or import RFdiffusion as a Python library, start with Docker.

This guide covers which version of the tool you actually want in 2025, the install steps that work today, the first-run gotcha that looks like a freeze, and the specific error messages people hit on RTX 50-series and ARM hardware.

Which RFdiffusion? v1, RFdiffusion2, or RFdiffusion3

This is the first decision and most tutorials skip it – they were written before the forks existed. As of late 2025, there are three separate codebases in three separate repos, none of which share code with the others.

The original v1.1.0 is still the right pick for most users. RFdiffusion2, released publicly on September 15, 2025, added atomic-motif enzyme design – benchmarking on the new Atomic Motif Enzyme set found solutions to all 41 active sites, compared to 16 out of 41 for v1. RFdiffusion3 followed on December 3, 2025, targeting proteins that interact with essentially any cellular molecule. Turns out it shares zero code with v1 or v2 – so the install steps below do not transfer to either newer version.

There’s something worth sitting with here: the field moved fast enough that three incompatible tools share a name. If you’re reading an install guide from 2023 or early 2024, there’s a real chance it’s pointing you at the wrong repo for what you’re actually trying to do. The version table above is the thing to bookmark.

System requirements

• OS: Linux x86_64 – Ubuntu 20.04 or 22.04 is the safest bet. No official macOS support; community options exist but are outside the scope of this guide.
• GPU: NVIDIA with CUDA 11.1+ (as of the current SE3nv.yml, which targets CUDA 11.1 – see the CUDA trap below before touching anything).
• RAM: 16 GB minimum, 32 GB comfortable.
• Disk: ~10 GB for model weights plus environment.
• Software: Docker 20+ or conda/mamba + git.

The Docker route (recommended)

Official Docker images are maintained by Rosetta Commons (Hope Woods and Sergey Lyskov). The beta documentation site went live in July 2025.

# 1. Pull the image
docker pull rosettacommons/rfdiffusion:latest

# 2. Create a working directory for inputs/outputs
mkdir -p ~/rfd/{inputs,outputs,models}

# 3. Download model weights into ~/rfd/models (see next section)

# 4. Run a smoke test - generate one unconditional 100aa backbone
docker run --rm --gpus all 
 -v ~/rfd/models:/app/RFdiffusion/models 
 -v ~/rfd/outputs:/app/RFdiffusion/outputs 
 rosettacommons/rfdiffusion:latest 
 inference.output_prefix=outputs/smoke 
 inference.num_designs=1 
 'contigmap.contigs=[100-100]'

Need a hosted HTTP endpoint rather than a CLI container? As of 2025, NVIDIA publishes NIM for RFdiffusion at nvcr.io/nim/ipd/rfdiffusion:2, which exposes a REST API on port 8000. That’s the path most production pipelines take.

Model weights

The code does nothing without weights. The minimum you need is Base_ckpt.pt; binder design also needs Complex_base_ckpt.pt. Both are hosted at files.ipd.uw.edu:

cd ~/rfd/models
wget http://files.ipd.uw.edu/pub/RFdiffusion/6f5902ac237024bdd0c176cb93063dc4/Base_ckpt.pt
wget http://files.ipd.uw.edu/pub/RFdiffusion/e29311f6f1bf1af907f9ef9f44b8328b/Complex_base_ckpt.pt
wget http://files.ipd.uw.edu/pub/RFdiffusion/5532d2e1f3a4738decd58b19d633b3c3/ActiveSite_ckpt.pt

Additional checkpoints (Complex_Fold_base_ckpt.pt, InpaintSeq_ckpt.pt, InpaintSeq_Fold_ckpt.pt, the beta and epoch8 variants) cover scaffold-guided design, inpainting, and active-site scaffolding. Only pull them if your inference flags actually call for them – the README documents which flag loads which checkpoint.

The source install – when you actually need it

You need source if you want to import RFdiffusion as a Python library (a refactor enabled this – run_inference.py now lives in scripts/, not the repo root) or if you need to modify inference code. The sequence from the official README:

git clone https://github.com/RosettaCommons/RFdiffusion.git
cd RFdiffusion
conda env create -f env/SE3nv.yml
conda activate SE3nv
cd env/SE3Transformer
pip install --no-cache-dir -r requirements.txt
python setup.py install
cd ../..
pip install -e .

According to the official README, total setup should take less than 30 minutes on a standard desktop. That assumes the CUDA version matches – which is the trap:

The CUDA 11.1 trap: Before running conda env create, check your driver with nvidia-smi and look at the cudatoolkit=11.1 pin in env/SE3nv.yml. If your driver is for CUDA 12.x and you don’t edit this line, conda will silently install the CPU build of PyTorch. You’ll only find out 50 timesteps into your first run – when it crashes.

Verify it works

Two checks. First, confirm PyTorch sees the GPU:

conda activate SE3nv
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

If that prints False, stop – fix the CUDA install before anything else. Then run a 100-residue unconditional design:

./scripts/run_inference.py 
 'contigmap.contigs=[100-100]' 
 inference.output_prefix=test_outputs/test 
 inference.num_designs=1

The first launch will sit on ‘Calculating IGSO3’ for a few minutes before any GPU activity appears. This is one-time precomputation – it gets cached for all future runs (documented in the official README). Don’t kill it. Once that clears, RFdiffusion runs 50 diffusion timesteps by default (per the Meiler Lab tutorial) and deposits a PDB in test_outputs/.

Common errors and fixes

These come from actual GitHub issues, not the generic troubleshooting section of the README.

RuntimeError: NVTX functions not installed

CPU build of PyTorch. Run nvidia-smi to confirm your hardware supports at least CUDA 11.1, then reinstall PyTorch with CUDA support using -c pytorch to force the pytorch channel over conda-forge.

ImportError: cannot import name ‘SE3Transformer’

The python setup.py install step inside env/SE3Transformer was skipped or failed silently. The se3_transformer package must be installed from the version bundled in this repo – not from the general pip index. Re-run that block from inside the activated SE3nv env.

Empty SE3nv environment after conda env create

Documented in GitHub issue #341: conda list shows nothing in SE3nv after a reported-successful create, and running RFdiffusion gives ModuleNotFoundError. The conda solver failed silently on a channel conflict. Run conda env create -f env/SE3nv.yml --verbose to surface the real error – or skip conda entirely and use Docker.

RTX 50-series, GH200, or any CUDA 12.8 system

The bundled environment is incompatible. GitHub issues #349 and #398 document this: RFdiffusion runs fine on an RTX 2060 with CUDA 11.3, but on RTX 50-series hardware with CUDA 12.8 the conda environment breaks. Same story on aarch64 GH200 boxes. The fix: use Docker, or build a custom env with pytorch-cuda=11.7 or 11.8 and the matching DGL wheel.

What’s interesting about this pattern is that it’s not specific to RFdiffusion – it’s the same structural problem you hit with any research code that pins an old CUDA version. The conda solver doesn’t warn you, it just installs the CPU fallback and reports success. Worth keeping in mind any time you install a compute-heavy ML package from an academic lab.

Upgrade and uninstall

git pull in the cloned repo, then re-run pip install -e . from the root. If you have batch submission scripts, they need to point at scripts/run_inference.py – the refactor moved it from the old root-level location.

RFdiffusion2 and RFdiffusion3 are separate installs – separate directories, separate weights, separate conda envs. There’s no in-place upgrade path across major versions because there’s no shared code to migrate.

To uninstall: conda env remove -n SE3nv, delete the cloned repo, delete the model weights directory, and for Docker users docker rmi rosettacommons/rfdiffusion:latest. The IGSO3 cache lives inside the repo directory, so deleting the repo handles that too.

Where to go next

Start with the contig string syntax in the README – that’s the interface for telling the model what to design. Pair RFdiffusion with ProteinMPNN to turn the glycine backbone outputs into real sequences. Run a 10-design binder job against a known target from the PDB and compare outputs to the published examples in the original Nature paper (Watson et al., 2023) – that’s the fastest way to confirm everything downstream of inference is also wired up correctly.

One thing that remains genuinely unclear across all three versions: there’s no single benchmark comparing wall-clock inference time on consumer vs. datacenter GPUs across representative design tasks. If your lab is deciding between running locally on an RTX 4090 and spinning up cloud A100 instances, that data doesn’t exist in one place yet. The GitHub discussions have scattered data points, but nothing systematic.

FAQ

Can I run RFdiffusion on a Mac?

For v1 and v2, no – the SE3-Transformer kernels require CUDA. For RFdiffusion3, there are community-maintained forks targeting Apple Silicon, but these are not officially supported and their status changes. Check the RFdiffusion3 repo issues for the current state before spending time on it.

How much VRAM do I actually need?

The GitHub issues have scattered reports – RTX 2060 (8 GB) working for smaller monomer designs, larger symmetric assemblies needing more. No official VRAM table exists. The most reliable approach: check the issues for your specific card and residue count before committing to hardware.

Do I really need all the model checkpoints?

No. Most users only ever load Base_ckpt.pt and Complex_base_ckpt.pt. The InpaintSeq, ActiveSite, and Fold-conditioned checkpoints are only loaded when you pass the corresponding inference flags. If you’re not running scaffold-guided design or inpainting, skip them.