Install AlphaFold 3 v3.0.4: Docker Deploy Guide

Most AlphaFold write-ups still open like a paper abstract. Skip that. As of v3.0.4 (28 July 2026), the same inference stack that used to assume an A100 can limp along on plain CPU – and on Apple Silicon the experimental MPS path lands about 3× CPU speed on an M3 MacBook Pro. You will not fold a 5,120-token complex on a laptop. You can smoke-test the install before you burn cloud GPU budget.

This guide targets AlphaFold 3 v3.0.4 only: clone the tag, pull ~630 GB of databases the right way, build the Docker image (including the RHEL ulimit trap), mount weights outside the git tree, and prove JAX sees a device. Specs and flags below match the v3.0.4 docs and release notes; anything undated here may have changed after that tag.

System Requirements for AlphaFold 3

Linux + NVIDIA is still the supported production path. v3.0.4 adds CPU-only and experimental Apple Silicon edges. Use the table for procurement; treat host CUDA and disk as the two places teams usually under-buy.

MSA search is CPU- and I/O-bound. Diffusion wants the GPU. Labs that care about invoices run data pipeline on cheap CPU nodes, then ship enriched JSON to A100/H100 only for --run_data_pipeline=false inference.

Download Source, Databases, and Weights

Start from the official repo and pin the tag so the image matches the release you think you are running.

1. Clone: git clone https://github.com/google-deepmind/alphafold3.git && cd alphafold3 && git checkout v3.0.4
2. Debian/Ubuntu helpers: sudo apt install wget zstd
3. Databases: ./fetch_databases.sh /data/af3_dbs – pulls BFD-small, MGnify, PDB mmCIF, PDB seqres, UniProt, UniRef90, NT, RFam, RNACentral from the GCS mirror. About 252 GB down, ~630 GB uncompressed; budget ~45 minutes on fast SSD. Keep the job inside tmux/screen. Default in scripts is $HOME/public_databases if you omit the path.
4. Weights: fetch af3.bin.zst into something like /data/af3_models. Use sits under the Weights Terms of Use – non-commercial organizations for parameters/output unless you hold a separate agreement.

Placement (read once, then obey):DB_DIR and the model directory must live outside the alphafold3 git tree. Put them inside and docker build tries to ship hundreds of GB into the build context. After download: sudo chmod 755 --recursive /data/af3_dbs. Missing r/w on the DB tree shows up later as opaque MSA-tool failures, not a clear permission error.

Install AlphaFold 3 with Docker

Host stack: Docker Engine, NVIDIA Container Toolkit, nvidia-smi clean after any fresh driver install. Container side expects CUDA 12.6 on the host.

# Inside alphafold3/ at v3.0.4
docker build -t alphafold3:v3.0.4 -f docker/Dockerfile .

# AlmaLinux / Rocky / RHEL - raise nofile or uv sync dies
docker build --ulimit nofile=65535:65535 -t alphafold3:v3.0.4 -f docker/Dockerfile .

On RHEL-family hosts that ulimit is not optional. Community threads (including issue #612) and the current installation.md both land on the same string: No file descriptors available (os error 24) during uv sync when the default is too low.

Cluster forbids Docker at runtime? Build once, push to a local registry, then singularity build alphafold3.sif docker://localhost:5000/alphafold3:v3.0.4. Bare-metal uv + HMMER is documented for CPU/Mac if you cannot use containers at all – same installation.md CPU/Apple section.

First-Time Configuration and a Minimal Run

Two empty dirs and a tiny monomer JSON beat a full complex for the first pass. Seeds stay at one until the path is proven.

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

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

Stage split on real work: --run_inference=false on a CPU box writes MSAs/templates into JSON; GPU workers take --run_data_pipeline=false across seeds. That is the usual lever when A100 hours are the scarce resource.

CPU host flags: --jax_backend=cpu --flash_attention_implementation=xla (expect on the order of 100× slower than a supported 80 GB GPU per v3.0.4 notes). Apple Silicon experiment: --jax_backend=mps. V100 / other CC 7.x: the official Dockerfile already sets XLA_FLAGS=--xla_disable_hlo_passes=custom-kernel-fusion-rewriter; bare-metal runs without it produce clashing residues and ranking scores around -99 (known_issues.md / performance.md).

Verify the Install Works

# GPU visible to Docker?
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

# JAX device list inside the AF3 image
docker run --rm --gpus all --entrypoint python alphafold3:v3.0.4 
 -c "import jax; print(jax.devices())"

# After a job: ranked mmCIF + confidence JSON under af_output/

Direct uv installs can also gate on uv run python run_alphafold_data_test.py when that test binary is present. There is no reliable global --version banner on every entrypoint – image tag + git checkout are the source of truth for v3.0.4.

Common Install Errors and Fixes

• No file descriptors available (os error 24) in uv sync – rebuild with --ulimit nofile=65535:65535 (Alma/Rocky/RHEL).
• MSA tools fail with nonsense / permission errors on mounts – DB and weights outside the repo; chmod 755 -R on DB dir; fix host ownership before docker run.
• Build copies forever or disk fills mid-build – DB or weights accidentally under the build context.
• Clashing residues, ranking ≤ -99 on V100 – export the XLA custom-kernel-fusion disable flag if you are not using the stock Dockerfile env.
• error waiting for container: unexpected EOF – community reports (#392-class) under memory pressure; free RAM, restart the user Docker daemon, stop stacking huge jobs on one socket.
• Tokamax NotImplementedError: Not supported on gpu on MPS – safe to ignore; another kernel path is chosen.

Picture the genetic databases as a shared library every job checks out of. Wrong building, locked shelves, no write card – every borrower fails the same cryptic way. Path and permission mistakes dress up as “science bugs” when they are ops bugs.

Upgrade from Earlier 3.x and Cleanup

Code went Apache 2.0 in v3.0.3; weight terms did not. Commercial orgs still need a separate weights agreement even after git pull. v3.0.4 is mostly product surface: CPU/Apple paths, gs:// via etils, chain IDs in summary confidence JSON, lower outer-product memory, JAX 0.9.1→0.10.2 and Tokamax bump aimed at Blackwell unified memory.

1. Stop running containers.
2. cd alphafold3 && git fetch --tags && git checkout v3.0.4
3. Rebuild as alphafold3:v3.0.4. Reuse existing DB and model dirs – no re-download if you already hold the paper-matched set.
4. Smoke JSON first. Re-apply any local Dockerfile patches (ulimit, UV_LINK_MODE, extra env).

Cleanup: docker rmi alphafold3:v3.0.4 plus dangling layers; drop the clone if you do not need source; delete DB_DIR / model dir only when nothing mounts them. Singularity .sif files are ordinary files. No distro package to purge.

Is a local stack still worth it beside AlphaFold Server? Private sequences, full ligand/modification control, batch throughput – yes. One-off monomer with no compliance constraint – often no. That answer drifts every release cycle on both sides.

FAQ

Do I still need to “request” model parameters?

No form queue for the file itself anymore: pull af3.bin.zst from the public GCS URL. Terms still gate use. Commercial work needs a separate DeepMind arrangement. Re-read WEIGHTS_TERMS_OF_USE before production.

Can I run AlphaFold 3 without an NVIDIA GPU?

Yes on v3.0.4. --jax_backend=cpu plus --flash_attention_implementation=xla. Budget roughly two orders of magnitude more wall time than an 80 GB A100/H100 class card. MPS on Apple Silicon is experimental, not the numerically verified datacenter path. Practical pattern: MSA-only on any CPU box, move enriched JSON to a GPU node for inference only.

Why does local confidence look worse than AlphaFold Server on the same sequence?

Often the MSA, not the diffusion weights. Server-side search historically differed on sharded Jackhmmer --domZ behaviour, which can admit a deeper alignment on some inputs (protein-DNA cases show up in the tracker). Local installs can move closer by relaxing Jackhmmer/Nhmmer --domE ~100× or by following the sharded-database layout in performance.md. Model code and parameters match the paper stack; genetic search depth does not always. Enrich the MSA before blaming the head.

Next: check out v3.0.4, point fetch_databases.sh at fast disk outside the repo, pass --ulimit nofile=65535:65535 on RHEL-family builds, land one short smoke job, then scale. When you publish structures, cite Abramson et al., Nature 2024.