Skip to content
AI Tools

Install AlphaFold 3 v3.0.4 for Protein Structure Prediction

Deploy AlphaFold 3 v3.0.4 locally with Docker: system specs, exact commands, model params, databases, verification, and real install fixes for protein structure prediction.

6 min readIntermediate

Most people never need the full AlphaFold install – until they do

ColabFold and the AlphaFold Server choke on custom ligands, private sequences, large batches, or anything that must stay behind your firewall. When that happens, local protein structure prediction is the job. As of the v3.0.4 release (28 Jul), AlphaFold 3 also runs CPU-only and on Apple Silicon. Below is the Docker path for that release – not a history lesson, not a Colab walkthrough.

Repo: github.com/google-deepmind/alphafold3. Source is Apache 2.0 since v3.0.3; model weights stay under separate non-commercial terms. Method paper: Nature, Accurate structure prediction of biomolecular interactions with AlphaFold 3.

System requirements for AlphaFold 3 v3.0.4

Per installation.md (as of v3.0.4), full install is Linux-first with an NVIDIA GPU.

Component As documented Practical note
OS Linux Docs examples lean Ubuntu 22.04 LTS
GPU NVIDIA Compute Capability 8.0+ A100/H100 80 GB for large jobs
CUDA on host 12.6 Must be visible to the container
RAM ≥64 GB recommended Genetic search is the memory hog
Disk Up to ~1 TB; SSD recommended DBs alone ~630 GB unzipped
Long jobs 5120 tokens on 80 GB cards Smaller cards need shorter inputs

v3.0.4 adds pure CPU (slow) and Apple Silicon with GPU acceleration. Data pipeline stays CPU-bound; inference wants the NVIDIA path when you have it.

Download source, databases, and model parameters

Clone first:

git clone https://github.com/google-deepmind/alphafold3.git
cd alphafold3
# optionally: git checkout v3.0.4

Helpers: sudo apt install wget zstd git aria2 (or distro equivalent).

Databases – run under tmux/screen. Official script: ~252 GB download, ~630 GB after unpack:

./fetch_databases.sh $HOME/public_databases

Rule that saves rebuilds: never put <DB_DIR> inside the repo tree. Docker will try to copy the world. After fetch: sudo chmod 755 --recursive $HOME/public_databases. Opaque MSA failures often trace back to missing write/read bits or a DB path nested under alphafold3/.

Model parameters (URL as listed in current installation docs):

mkdir -p $HOME/af3_models
cd $HOME/af3_models
wget https://storage.googleapis.com/alphafold3/af3.bin.zst
# zstd -d af3.bin.zst if you need the unpacked binary

Weights fall under the AlphaFold 3 Model Parameters Terms of Use: non-commercial use by non-commercial organizations. Commercial access is a separate request ([email protected]) – the public GCS object does not change that.

Six hundred thirty gigabytes of MSA data is not a “download a wheel” moment. Think of it as stocking a reference library before the first fold: skip shelves and hard targets come back thin. Budget disk and patience up front, or the rest of this guide is theater.

Install: Docker + NVIDIA + build

Docs walk a rootless Docker setup. On Ubuntu-style hosts the shape is:

  1. Docker CE + plugins from Docker’s repo.
  2. Rootless stack: uidmap / systemd-container, then dockerd-rootless-setuptool.sh as in the install doc.
  3. NVIDIA driver via ubuntu-drivers (or vendor path); confirm nvidia-smi.
  4. NVIDIA Container Toolkit → nvidia-ctk runtime configure --runtime=docker → restart the user docker service.
  5. Smoke GPU: docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

Build from repo root:

docker build -t alphafold3 -f docker/Dockerfile .
# RHEL/Alma/Rocky hitting "No file descriptors available (os error 24)" during uv sync:
docker build --ulimit nofile=65535:65535 -t alphafold3 -f docker/Dockerfile .

That ulimit flag is called out in installation notes and GitHub issue threads when the default nofile ceiling collapses mid-sync.

Keep models and databases outside the git tree. Mounts stay boring; rebuilds stay fast.

First-time configuration and test run

Dirs + official-style example JSON (2PV7 dimer from the README pattern):

mkdir -p $HOME/af_input $HOME/af_output
cat > $HOME/af_input/fold_input.json << 'EOF'
{
 "name": "2PV7",
 "sequences": [{
 "protein": {
 "id": ["A", "B"],
 "sequence": "GMRESYANENQFGFKTINSDIHKIVIVGGYGKLGGLFARYLRASGYPISILDREDWAVAESILANADVVIVSVPINLTLETIERLKPYLTENMLLADLTSVKREPLAKMLEVHTGAVLGLHPMFGADIASMAKQVVVRCDGRFPERYEWLLEQIQIWGAKIYQTNATEHDHNMTYIQALRHFSTFANGLHLSKQPINLANLLALSSPIYRLELAMIGRLFAQDAELYADIIMDKSENLAVIETLKQTYDEALTFFENNDRQGFIDAFHKVRDWFGDYSEQFLKESRQLLQQANDLKQG"
 }
 }],
 "modelSeeds": [1],
 "dialect": "alphafold3",
 "version": 1
}
EOF

Launch:

docker run -it 
 --volume $HOME/af_input:/root/af_input 
 --volume $HOME/af_output:/root/af_output 
 --volume $HOME/af3_models:/root/models 
 --volume $HOME/public_databases:/root/public_databases 
 --gpus all 
 alphafold3 
 python run_alphafold.py 
 --json_path=/root/af_input/fold_input.json 
 --model_dir=/root/models 
 --output_dir=/root/af_output

Useful flags: --run_data_pipeline (default true, CPU) and --run_inference (default true, GPU). Split them when the search box and the GPU box are not the same machine.

Verify the install works

Logs should show MSA/template search, then diffusion. Success lands ranked structures plus confidence JSON under $HOME/af_output (mmCIF/PDB-style outputs; v3.0.4 summary confidence includes chain IDs). nvidia-smi during inference is the honest GPU check. Container-only smoke: docker run --rm alphafold3 python run_alphafold.py --help. Already passed the cuda 12.6 nvidia-smi test earlier? You are not starting from zero.

Common install errors and fixes

  • “No file descriptors available (os error 24)” during uv sync – add --ulimit nofile=65535:65535 on build (classic on Alma/Rocky/RHEL).
  • Permission denied / opaque MSA tool errors – DB and model dirs outside the repo; chmod 755 -R on both.
  • “error waiting for container: unexpected EOF” or missing docker sock after OOM (rootless) – community reports (e.g. multi-GPU threads) fix with pkill of leftover user docker bits or a clean re-login.
  • Clashing residues / ranking score -99 on V100 (CC 7.x) – from known_issues.md: XLA_FLAGS=--xla_disable_hlo_passes=custom-kernel-fusion-rewriter.
  • CUDA mismatch – host must present 12.6 into the runtime; re-run nvidia-ctk + service restart.

Input/output field details live in the repo’s docs/input.md and docs/output.md.

Odd question worth sitting with: if your first “successful” fold looks geometrically cursed only on older cards, is the install broken – or did a compiler pass rewrite kernels the hardware cannot digest? The V100 flag exists because that second answer showed up in real runs.

Upgrade, alternatives, uninstall

Upgrade path is dull on purpose: git pull or checkout a newer tag, rebuild the same image, refresh weights only when a new af3.bin.zst appears. Databases usually stay put unless fetch_databases.sh pins change.

HPC folks often wrap the same stack in Singularity/Apptainer. Plain conda on bare metal is possible and unsupported – JAX, HMMER, and custom ops fight you. ColabFold or alphafoldserver.com still fine for light work; they are not this guide.

Cleanup:

docker rmi alphafold3
rm -rf alphafold3 $HOME/af_input $HOME/af_output
# keep or delete $HOME/public_databases and $HOME/af3_models (hundreds of GB)

Rootless leftovers: stop the user docker service; remove ~/.config/docker if you want a full wipe.

Next step is boring in a good way. Real FASTA → new JSON per input docs → same docker run. Hardware you control, weights terms respected.

FAQ

Does AlphaFold 3 v3.0.4 require a GPU?

No. CPU-only and Apple Silicon work in v3.0.4. NVIDIA still wins on speed for inference.

How much disk do the genetic databases really need?

About 252 GB down, roughly 630 GB unpacked, on SSD if you care about MSA wall time. Example: a laptop with 400 GB free will finish the wget and then die on decompress – free the full footprint first. fetch_databases.sh pulls the set the pipeline expects; subsets are an experiment, not the default quality path.

Can I use the model weights commercially?

Not under the standard WEIGHTS_TERMS_OF_USE. Non-commercial organizations, non-commercial use. Source code is Apache 2.0; weights are not. Ask the AlphaFold team for commercial terms before you plan a product pipeline around af3.bin.zst. Structure outputs are computational models – not clinical truth.

Related AI Tools