Installation¶

This guide walks through installing AlphaFold 3 on an Apple Silicon Mac using the interactive installer. The installer handles all dependencies, builds the required tools, and creates a ready-to-use server configuration.

Prerequisites¶

Hardware¶

AlphaFold 3 runs natively on Apple Silicon Macs. The following chips are supported:

Software¶

The installer checks for and, where possible, automatically installs these dependencies:

Disk Space¶

At least 5 GB of free disk space is required. The installer will warn if disk space is low.

Step 1: Obtain Model Weights¶

AlphaFold 3 model weights are provided by Google DeepMind under a separate license. You must request access before installing.

1. Complete the model parameters request form.
2. Google DeepMind will review your request (typically 2--3 business days).
3. Once approved, download the weight file (af3.bin.zst, approximately 973 MB).
4. Place it in a directory of your choice. The default location is:

~/.alphafold3/weights/model/af3.bin.zst

Recognized Weight Formats¶

The installer and runtime accept any of these file patterns:

• af3.bin.zst (single compressed file)
• af3.bin (uncompressed)
• af3.0.bin.zst (sharded, numbered)
• af3.bin.zst.0, af3.bin.zst.1, ... (split shards)

Step 2: Clone the Repository¶

git clone https://github.com/omrikais/alphafold3-mac.git
cd alphafold3-mac

Step 3: Run the Installer¶

There are two ways to start the installer:

./scripts/install.sh

Dry Run¶

To preview what the installer will do without making any changes:

./scripts/install.sh --dry-run

This exercises all prompts and validation logic but skips actual installations and file writes.

Install Mode Selection¶

The installer presents two modes:

Choose Full install to get the web interface with 3D structure visualization, job management, and real-time progress tracking. Choose CLI-only if you prefer command-line workflows or don't have Node.js installed.

Configuration Prompts¶

The installer asks for four pieces of configuration:

Model Weights Directory¶

Enter weights directory [~/.alphafold3/weights/model]:

Point this to the directory containing your downloaded af3.bin.zst file. The installer validates that a recognized weight file exists in this directory.

Genetic Databases (Optional)¶

The installer presents three options for database setup:

Option 1 validates that the directory contains the required database files:

• uniref90_2022_05.fa
• mgy_clusters_2022_05.fa
• bfd-first_non_consensus_sequences.fasta
• uniprot_all_2021_04.fa
• pdb_seqres_2022_09_28.fasta
• mmcif_files/ (or pdb_2022_09_28_mmcif_files/mmcif_files/)

RNA databases are checked but are optional:

• nt_rna_2023_02_23_clust_seq_id_90_cov_80_rep_seq.fasta
• rfam_14_9_clust_seq_id_90_cov_80_rep_seq.fasta
• rnacentral_active_seq_id_90_cov_80_linclust.fasta

Option 2 prompts for a target directory (default ~/public_databases), checks disk space (warns if less than 650 GB free), verifies that curl, tar, and zstd are available (offering to install zstd via Homebrew if missing), and then downloads all databases after the main installation steps complete. Downloads are resumable -- if interrupted, re-run the installer and choose option 2 with the same directory, or run the fetch script directly:

bash fetch_databases.sh ~/public_databases

If the download is incomplete, the installer defaults to clearing the database path so the server starts in sequence-only mode. You can explicitly choose to keep a partial path if you plan to finish downloading later.

Option 3 skips database setup entirely. The server runs in sequence-only mode, which still produces high-quality predictions for many cases.

Data Directory¶

Enter data directory [~/.alphafold3_mlx/data]:

This is where job history (SQLite database), prediction outputs, and MSA cache files are stored. The default is ~/.alphafold3_mlx/data.

Server Port¶

Enter port number [8642]:

The port for the web server. Must be between 1024 and 65535. The installer checks that the port is not already in use.

What the Installer Does¶

After collecting configuration, the installer runs these steps:

Each step shows a progress indicator and elapsed time. If a step fails, the installer offers to retry it before exiting.

What Gets Created¶

After a successful installation, the following files and directories exist:

Step 4: Start the Server¶

After installation, there are several ways to start the server.

cd /path/to/alphafold3-mac
./scripts/start.sh

cd /path/to/alphafold3-mac
source .venv/bin/activate
python3 -m alphafold3_mlx.api --port 8642

When the server starts, you'll see:

  AlphaFold 3 MLX
  ────────────────────────────────
  Web UI:  http://127.0.0.1:8642
  API:     http://127.0.0.1:8642/api

  Press Ctrl+C to stop the server.

Open http://127.0.0.1:8642 in your browser to access the web interface.

Server Command-Line Options¶

When using python3 -m alphafold3_mlx.api directly, the following options are available:

Stopping the Server¶

Press Ctrl+C in the Terminal window running the server. If you used the Desktop launcher, simply close the Terminal window.

Step 5: Verify Installation¶

Run these checks after first startup to confirm the install is complete.

1) API health check¶

curl http://127.0.0.1:8642/api/system/status

Expected result: JSON including model status, queue status, and hardware info.

2) Input validation check¶

curl -X POST http://127.0.0.1:8642/api/validate \
  -H "Content-Type: application/json" \
  -d @examples/desi1_monomer.json

Expected result: JSON with valid: true for a valid sample input.

3) CLI smoke test¶

source .venv/bin/activate && PYTHONPATH=src python3 run_alphafold_mlx.py \
  --input examples/desi1_monomer.json \
  --output_dir output/install_verify \
  --num_samples 1 \
  --diffusion_steps 20

Expected result: successful completion and output files under output/install_verify.

Using the CLI Instead¶

If you prefer command-line workflows, you can run predictions directly without the web server:

cd /path/to/alphafold3-mac
./scripts/alphafold3.sh \
    --input examples/desi1_monomer.json \
    --output_dir output/my_prediction

Or equivalently:

source .venv/bin/activate
python3 run_alphafold_mlx.py \
    --input examples/desi1_monomer.json \
    --output_dir output/my_prediction

The alphafold3.sh wrapper automatically loads your config.env (setting weight paths, HMMER paths, etc.) before running the CLI.

See the CLI Reference for all available options.

Obtaining Genetic Databases (Optional)¶

Genetic databases enable MSA (Multiple Sequence Alignment) search, which can improve prediction quality. Without databases, AlphaFold 3 runs in sequence-only mode using placeholder MSA data.

Downloading Databases¶

The easiest way to download databases is to choose option 2 during installation. The installer handles disk space checks, tool dependencies, and download progress automatically.

If you skipped databases during installation or need to download them separately, use the provided fetch script:

bash fetch_databases.sh ~/public_databases

The script supports resuming interrupted downloads -- files that already exist are skipped automatically. If a download was interrupted mid-file, re-running the script resumes from where it left off.

This downloads and decompresses the following from Google Cloud Storage:

Recovering from Interrupted Downloads¶

If the database download was interrupted (by Ctrl+C, network loss, or system sleep), you have two options:

1. Re-run the installer and choose option 2 with the same target directory. Completed files are skipped automatically.

2. Run the fetch script directly:

   bash fetch_databases.sh ~/public_databases
   

After the download completes, update your configuration:

nano ~/.alphafold3_mlx/config.env
# Set: AF3_DB_DIR="/path/to/public_databases"

Then restart the server.

Configuring Database Paths¶

If you skipped databases during installation and want to add them later, edit your configuration file:

nano ~/.alphafold3_mlx/config.env

Set the AF3_DB_DIR value to your databases directory:

AF3_DB_DIR="/path/to/public_databases"

Then restart the server. When AF3_DB_DIR is set, the server automatically enables the data pipeline for MSA and template search.

Per-Database Environment Variables¶

For advanced setups where databases are split across multiple locations, you can set individual database paths:

These override the automatic lookup from AF3_DB_DIR.

Configuration Reference¶

All configuration is stored in ~/.alphafold3_mlx/config.env. This file is created by the installer and loaded by start.sh and alphafold3.sh.

Config File Format¶

# AlphaFold 3 MLX Configuration
# Edit this file to change settings, then restart the server.

AF3_WEIGHTS_DIR="/Users/you/.alphafold3/weights/model"
AF3_DATA_DIR="/Users/you/.alphafold3_mlx/data"
AF3_DB_DIR=""
AF3_PORT="8642"
AF3_INSTALL_DIR="/Users/you/alphafold3-mac"
AF3_JACKHMMER="/Users/you/.alphafold3_mlx/hmmer/bin/jackhmmer"
AF3_HMMSEARCH="/Users/you/.alphafold3_mlx/hmmer/bin/hmmsearch"
AF3_HMMBUILD="/Users/you/.alphafold3_mlx/hmmer/bin/hmmbuild"
AF3_NHMMER="/Users/you/.alphafold3_mlx/hmmer/bin/nhmmer"
AF3_HMMALIGN="/Users/you/.alphafold3_mlx/hmmer/bin/hmmalign"

Config Keys¶

To apply changes, edit the file and restart the server.

API Authentication (Optional)¶

To protect your server with Bearer token authentication:

1. Set the AF3_API_KEY environment variable before starting the server:

   export AF3_API_KEY="your-secret-token"
   ./scripts/start.sh
   

2. Or pass it directly:

   source .venv/bin/activate
   python3 -m alphafold3_mlx.api --api-key "your-secret-token"
   

When enabled, all API requests must include the token:

curl -H "Authorization: Bearer your-secret-token" \
     http://127.0.0.1:8642/api/system/status

Or as a query parameter: http://127.0.0.1:8642/api/system/status?token=your-secret-token

Development Mode¶

For contributors or developers who want to modify the web interface with hot-reload:

./scripts/dev.sh

This starts:

• FastAPI backend on port 8642 (with auto-reload)
• Next.js dev server on port 3001 (with hot module replacement)

Open http://localhost:3001 for the development frontend. Logs are written to .dev-logs/fastapi.log and .dev-logs/nextjs.log.

To stop both servers:

./scripts/dev-stop.sh

Re-running the Installer¶

It is safe to re-run the installer at any time. It will:

• Skip steps that are already complete (existing venv, already-installed tools)
• Overwrite ~/.alphafold3_mlx/config.env with new settings
• Rebuild the frontend if in full mode

./scripts/install.sh

Troubleshooting¶

"Python 3.12+ required"¶

Install Python 3.12 via Homebrew:

brew install python@3.12

Then re-run the installer. It will detect python3.12 automatically.

"Node.js >= 20 required"¶

Install Node.js 20 via Homebrew:

brew install node@20

Or choose CLI-only mode during installation to skip the Node.js requirement.

"Port already in use"¶

Another process is using the configured port. Either:

• Stop the process using that port
• Choose a different port during installation
• Edit ~/.alphafold3_mlx/config.env and change AF3_PORT

HMMER Build Fails¶

If the HMMER build step fails, try building it manually:

./scripts/build_hmmer_macos.sh --prefix=$HOME/.alphafold3_mlx/hmmer

This requires autoconf and automake (installed via Homebrew).

Server Starts but Jobs Fail¶

Check that model weights are in place:

ls ~/.alphafold3/weights/model/af3.bin.zst

If the file doesn't exist, download it from Google DeepMind (see Step 1) and place it in the configured weights directory.

Memory Errors on Large Inputs¶

For inputs with many tokens (large proteins or complexes), you may run out of unified memory. Try:

• Using --precision float16 or --precision bfloat16 (M3/M4) to halve memory usage
• Reducing --num-samples to 1
• Closing other memory-intensive applications

See Performance for memory optimization guidance.

Next Steps¶

• Quickstart -- Run your first prediction
• Input Format -- Learn how to prepare input JSON files
• Output Format -- Understand prediction outputs
• Pipeline Setup -- Configure MSA and template search
• CLI Reference -- Full command-line options