Searching AlphaFold Metagenomic Structures with Foldseek

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-11-11

By the end of this guide you will be able to take a protein sequence or structure from a metagenomic sample, search it against the metagenomic portion of the AlphaFold Protein Structure Database with Foldseek, and decide which hits deserve a functional annotation. You will install Foldseek, prepare a query model, run searches from both the web server and the command line, read the tabular output format, filter results with sensible thresholds, and validate a hit before you write a claim about it.

Here is what you need on hand. For the full experience, a Linux, macOS, or Windows (WSL2) machine with several hundred gigabytes of free disk, because the prebuilt metagenomic target databases are large. For a first attempt, a browser is enough, because the Foldseek web server runs the same searches against prebuilt targets. Optional but useful: ColabFold or the AlphaFold Server for turning your own sequences into query models, and a molecular graphics program such as ChimeraX or PyMOL for checking alignments by eye.

The motivation is simple. Metagenomic sequencing keeps revealing vast, previously unseen microbial and viral diversity, while standard homology tools such as BLAST and HMMER often fail on highly divergent genomes [1]. Structure closes part of that gap, and Foldseek is the tool that makes structure search fast enough to run at metagenomic scale.

Why Structure Search Belongs in Metagenomic Annotation

Metagenomics is the sequencing of genetic material recovered directly from environmental samples such as soil, seawater, or the gut, without culturing the organisms first. Most proteins coming out of these projects have no characterized relative, and a large fraction have no confident function at all.

Sequence similarity loses power quickly as evolutionary distance grows, because amino acid identity decays faster than three-dimensional structure. A protein can retain the same fold, meaning the same packed arrangement of helices and strands, long after sequence identity between distant relatives drops below the level a sequence aligner can trust. Function tends to live in the fold, in the geometry of active sites and binding surfaces, so a confident fold match can support a functional hypothesis when sequence evidence is silent.

This is the gap the structure-based toolkit fills. A recent review of computational viromics describes structure-aware frameworks, AlphaFold, ESMFold, and Foldseek, as the route to annotating highly divergent viral proteins through conserved 3D folds [1]. AlphaFold and ESMFold predict a structure from a sequence. Foldseek then searches that predicted structure against enormous libraries of predicted and experimental structures, turning fold comparison into something with the workflow and cost profile of a sequence search.

Two cautions belong up front. Predicted structures carry per-residue confidence values, and low-confidence regions can imitate folds that do not exist. Structure similarity alone also does not prove common ancestry, because a handful of folds recur across unrelated protein lineages. Both problems have concrete checks, covered in the validation and limitations sections.

What the AlphaFold Metagenomic Structure Database Contains

The AlphaFold Protein Structure Database (AFDB) is hosted by EMBL-EBI at alphafold.ebi.ac.uk. It launched in 2021 with predicted structures for the human proteome and a set of key model organisms. In 2022 it expanded to more than 200 million structures covering nearly all cataloged proteins known to science, and a large share of those proteins come from metagenomes, deposited through UniProt entries derived from MGnify, EMBL-EBI's resource for assembling and analyzing metagenomic data. In 2024 the database gained additional metagenomic structures predicted with AlphaFold 3, the successor model that also handles complexes with nucleic acids, ligands, and ions.

Three properties of AFDB shape how you should search it:

1. Models are single polypeptide chains. Protein-protein and protein-ligand contacts are not modeled in the classic AFDB entries, so a fold that only stabilizes inside a complex may look different or disordered.
2. Every residue carries a confidence value. The pLDDT (predicted local distance difference test) runs from 0 to 100 and is stored in the B-factor column of each file. Scores above 90 indicate very high confidence, 70 to 90 confident backbone, 50 to 70 low confidence, and below 50 very low confidence, which often means intrinsic disorder.
3. Files are mmCIF. AFDB distributes structures in mmCIF (macromolecular Crystallographic Information File), the format the PDB archive now uses for large structures. Individual files follow the pattern AF-{UniProt accession}-F1-model_v4.cif, and bulk downloads are available from the EBI FTP server at ftp.ebi.ac.uk/pub/databases/alphafold/, organized into folders keyed by accession prefix, with Parquet metadata files alongside.

A sibling resource matters here too. The ESM Metagenomic Atlas, produced by Meta AI with the ESMFold language model, contains more than 600 million predicted structures of metagenomic proteins. Foldseek can search it with the same commands, and the prebuilt esmatlas databases make it an easy second opinion when AFDB hits run dry.

Finally, keep predicted and experimental structures mentally separate. Everything in AFDB and the ESM Atlas is a prediction with confidence attached. The PDB holds experimentally determined structures and remains the gold standard for detailed mechanism work.

How Foldseek Compares Structures at Sequence-Search Speed

Classical structural aligners such as TM-align and DALI perform expensive geometry optimization and are far too slow for millions of structures. Foldseek gets around this with the 3Di alphabet, a 20-letter structural alphabet in which each letter summarizes the local backbone conformation of a residue and the interaction pattern it makes with nearby residues. A protein structure becomes a string over this alphabet, so structure comparison turns into string comparison, which can be prefiltered and aligned with the same tricks that make BLAST-class tools fast.

A Foldseek alignment is scored on a combination of 3Di letters and amino acid letters, then refined with a TM-align-style optimization of the superposition. The practical result is sensitivity close to slow structural aligners at a cost close to sequence search, which is what makes a search against hundreds of millions of structures feasible on ordinary hardware.

Three scores appear throughout the output, and you should be able to read all of them:

• TM-score, short for Template Modeling score, runs from 0 to 1 and measures global fold similarity in a length-normalized way. A score of 1 means a perfect match. As a long-standing rule of thumb, TM-scores above 0.5 usually indicate the same fold, and scores below about 0.4 usually indicate different folds.
• RMSD (root mean square deviation) is the average deviation between superposed atoms in angstroms. It is informative only together with the number of aligned residues, because a small RMSD over three residues means almost nothing.
• LDDT (local distance difference test) runs from 0 to 1 and measures how well local atom environments are preserved, which complements RMSD by rewarding correct local packing even when flexible ends swing around.

Web Server or Command Line? Sorting Out the Servers

Three different things in this workflow get called a server, and mixing them up causes most beginner confusion.

Use the Foldseek web server when you want to try a search in the next five minutes. You paste a sequence or upload a PDB or mmCIF file, pick a target database, and get back ranked hits with probabilities, TM-scores, and clickable 3D superpositions. Use the command line when you need batching, custom target databases, reproducible parameters, or output you can pipe into scripts. Use the AlphaFold Server when you need a brand-new prediction, especially of a complex, rather than a search against existing models.

Installing Foldseek

Pick one of these routes.

# Option 1, Bioconda
conda install -c bioconda foldseek

# Option 2, Homebrew on macOS
brew install foldseek

# Option 3, static Linux binary
wget https://mmseqs.com/foldseek/foldseek-linux-avx2.tar.gz
tar xvzf foldseek-linux-avx2.tar.gz
export PATH=$(pwd)/foldseek/bin:$PATH

# Option 4, Docker
docker pull ghcr.io/steineggerlab/foldseek

Verify the install and skim the help for the module you will use most:

foldseek version
foldseek --help
foldseek easy-search -h

The version command prints a build string. If the shell cannot find the binary, revisit the PATH export from option 3 or activate the conda environment.

From Metagenomic Sequence to Query Model: A Short AlphaFold Tutorial

Foldseek aligns structures, so the first job is producing a query structure. You have three routes.

Route A, the protein already has an AFDB model. Search the UniProt accession at alphafold.ebi.ac.uk and download the mmCIF. This is the fastest path and also gives you a pLDDT profile before you commit to anything.

Route B, predict locally with ColabFold. ColabFold is the widely used community reimplementation of AlphaFold 2. After installing it following the project README, a single command predicts a structure from a FASTA file:

pip install "colabfold[colabfold] @ git+https://github.com/sokrypton/ColabFold"
colabfold_batch orf_cluster_21.fasta orf_cluster_21_out/

The output directory contains a ranked set of PDB models, with the top-ranked model usually the one you search, plus per-model confidence scores. For an ORF (open reading frame, a translatable stretch of codons) from a metagenome with no database relatives, expect modest confidence and judge the model residue by residue.

Route C, the AlphaFold Server. Open the AlphaFold Server web application in a browser, sign in with a Google account, specify your protein sequences and optionally nucleic acids, ligands, or ions, submit the job, and download the mmCIF when it finishes. The terms of use restrict it to non-commercial work, and daily submission limits apply. Complex predictions arrive as one multi-chain file, so split chains before searching, because AFDB stores single chains.

Whichever route you take, consider trimming low-confidence tails before searching. Many pipelines drop residues with pLDDT below 70, because disordered termini are a reliable source of spurious fold matches. Foldseek reads both PDB and mmCIF, so no format conversion is needed.

Worked Example: Searching AlphaFold Metagenomic Structures with Foldseek

This walkthrough is a complete AlphaFold metagenomics Foldseek example you can adapt. It uses a small, famous query so every step is reproducible on a laptop, then scales the same commands to the metagenomic target database.

Step 1: Set up a workspace and fetch a query structure

mkdir afdb_demo && cd afdb_demo
wget https://files.rcsb.org/download/1UBQ.pdb

1UBQ is the crystal structure of human ubiquitin, 76 residues, one chain, a compact alpha-beta fold. Any PDB or mmCIF file works here, including your own ColabFold or AlphaFold Server models.

Step 2: Warm up the pipeline against the PDB

Before touching a terabyte-scale target, prove the plumbing with a small database:

foldseek databases PDB pdb pdb_tmp
foldseek easy-search 1UBQ.pdb pdb pdb_hits.m8 pdb_hits.html pdb_tmp

The first command downloads the prebuilt PDB target database. The second runs the search. easy-search takes the query, the target database, the alignment output file, an HTML report file, and a scratch directory, in that order. Look at the first line of pdb_hits.m8:

1UBQ_A	1UBQ_A	100.000	76	0	1	76	1	76	6.7e-37	141

(Values illustrative.) This is the default 11-column tabular format, and the top hit is the query against itself with 100 percent identity, which confirms the pipeline works. If this file is empty, fix the setup before downloading anything large.

Step 3: Download a metagenomic target database

foldseek databases Alphafold/Alphafold-Mgnify afdb_meta db_tmp

This fetches the prebuilt Foldseek version of the AlphaFold metagenomic structures. Two honest warnings. First, database names and sizes change between Foldseek releases, so run foldseek databases and copy the exact AlphaFold metagenomic entry name your installation prints. A typical listing looks like this (abbreviated):

Alphafold/Alphafold-Proteomes    AlphaFold proteomes
Alphafold/Alphafold-Swiss-Prot   AlphaFold Swiss-Prot
Alphafold/Alphafold-UniProt      AlphaFold UniProtKB
Alphafold/Alphafold-Mgnify       AlphaFold MGnify metagenomic structures
esmatlas                         ESM Metagenomic Atlas
esmatlas-compress                ESM Metagenomic Atlas, compressed
PDB                              Experimental PDB structures

Second, expect a download measured in hundreds of gigabytes and several hours. If that is more than your machine can hold, start with the AlphaFold Swiss-Prot or proteomes entries, or the esmatlas entries, and graduate to the full metagenomic set later.

Step 4: Run the search with a rich output format

foldseek easy-search 1UBQ.pdb afdb_meta meta_hits.m8 meta_hits.html db_tmp \
  --threads 16 \
  --max-seqs 1000 \
  --format-output "query,target,pident,alnlen,gapopen,qstart,qend,tstart,tend,evalue,bits,alntmscore,qtmscore,ttmscore,rmsd,lddt,qcov,tcov,prob"

Three choices matter here. Raising max-seqs matters because the default of 25 truncates the candidate list before you ever get to filter it. The format-output string defines your columns, and the tokens above add structure-specific scores to the standard tabular set. The threads value should match your hardware.

Step 5: Read the first rows

1UBQ_A	A0A5B4AVU3	38.2	71	0	1	74	3	73	3.1e-11	52.6	0.72	0.71	0.69	1.8	0.81	0.93	0.95	0.98
1UBQ_A	A0A1W1X8H9	31.5	64	1	2	72	5	68	9.4e-08	44.1	0.61	0.60	0.58	2.6	0.74	0.84	0.82	0.91
1UBQ_A	Q6GSD8	24.7	41	2	9	49	17	57	0.45	18.0	0.31	0.30	0.28	5.9	0.52	0.54	0.51	0.55

(Values illustrative, accessions shown as placeholders for the accessions your search returns.) The first row is the kind of hit you want, with an alignment TM-score of 0.72, high coverage on both sides, and a probability near 1. The third row shows the junk pattern, low TM-scores, coverage around half, and an E-value near 1. In the target column, AFDB databases report UniProt accessions, which is the key you will use to retrieve each model.

Step 6: Filter on the columns that matter

awk -F'\t' '$12 >= 0.5 && $17 >= 0.7 && $19 >= 0.9' meta_hits.m8 > meta_hits.filtered.tsv

With the format string above, column 12 is alntmscore, column 17 is qcov, and column 19 is prob. The rule to remember is that a column index equals the position of its token in your format-output string, so if you edit the string, renumber the awk conditions.

Step 7: Resolve hits back to database entries

For each surviving hit, the target accession maps directly onto the AFDB URL patterns:

https://alphafold.ebi.ac.uk/entry/{ACCESSION}
https://alphafold.ebi.ac.uk/files/AF-{ACCESSION}-F1-model_v4.cif

To demonstrate the download pattern with a real accession, human hemoglobin subunit alpha lives at:

curl -O https://alphafold.ebi.ac.uk/files/AF-P69905-F1-model_v4.cif

If a download returns a 404, check the entry page for the current version suffix, because AFDB regenerates models over time and the suffix advances.

Step 8: Sanity check the top hit with a second scorer

foldseek easy-rmsd 1UBQ.pdb AF-A0A5B4AVU3-F1-model_v4.cif

(Second file name illustrative, substitute your hit.) This prints RMSD and TM-score for the optimal superposition of the pair, giving you an independent read on the alignment quality. Then open both structures in ChimeraX or PyMOL and superpose them, with matchmaker #1 to #2 in ChimeraX. Look for conserved core packing and plausible active-site geometry, not merely a similar count of helices and strands.

Reading the Foldseek Output Format

The default output is the m8 format, an 11-column tabular layout inherited from BLAST tabular convention: query, target, pident, alnlen, gapopen, qstart, qend, tstart, tend, evalue, bits. The format-output option replaces or extends this list with named tokens. The ones that matter for structure search:

Three interpretation habits will save you from bad annotations. First, apply the TM-score rule of thumb with length in mind, since short proteins reach high TM-scores by chance more easily, and the 0.5 threshold is a guideline rather than a cliff. Second, do not port BLAST E-value intuition blindly, because E-values depend on database size and composition, and a metagenomic structure database is a very different universe from a curated protein sequence database. Third, read qcov and tcov together with the TM-scores, because a 0.7 TM-score over 20 percent of the query usually describes a domain match, not a whole-protein match.

The HTML file from easy-search deserves a mention. Open it in a browser and you get an interactive 3D superposition for each hit, which is the fastest way to triage a result list before any scripted validation.

Key Options and When to Change Them

The single most common silent failure is leaving max-seqs at its default, running a search against a huge database, and concluding that a fold is rare when the tool simply stopped early. The second most common is choosing prefilter settings that exceed available memory on a large target, which the next section addresses.

A Reusable Workflow Template

The script below packages the whole search into a template you can adapt per project. Change the three variables at the top, adjust thresholds to your tolerance for false positives, and keep it under version control so your parameters are recorded.

#!/usr/bin/env bash
# foldseek-afdb-template.sh
# A workflow template for searching query structures against
# AlphaFold metagenomic structures with Foldseek.

QUERY=orf1/model.pdb          # your query, PDB or mmCIF
TARGET_DB=afdb_meta           # prebuilt foldseek target database
SCRATCH=./tmp                 # scratch space on your largest volume

mkdir -p "$SCRATCH"

foldseek easy-search "$QUERY" "$TARGET_DB" hits.m8 hits.html "$SCRATCH" \
  --threads 16 \
  --max-seqs 1000 \
  -e 0.001 \
  --format-output "query,target,pident,alnlen,gapopen,qstart,qend,tstart,tend,evalue,bits,alntmscore,qtmscore,ttmscore,rmsd,lddt,qcov,tcov,prob"

# Keep strong hits: alignment TM-score at least 0.5,
# query coverage at least 0.7, probability at least 0.9
awk -F'\t' '$12 >= 0.5 && $17 >= 0.7 && $19 >= 0.9' hits.m8 > hits.filtered.tsv

echo "Kept $(wc -l < hits.filtered.tsv) of $(wc -l < hits.m8) hits"
foldseek version > foldseek_version.txt

The final line matters more than it looks. Record the Foldseek version and the date you downloaded the target database, because both change over time and both change your results. If your goal is homology modeling rather than annotation, the same search doubles as template selection, so rank candidate structural templates by qtmscore and coverage and hand the superposition to your modeling tool.

Scaling Up to the Full Metagenomic Database

easy-search is ideal for a handful of queries. For a batch, build a query database once and use the two-step workflow:

foldseek createdb queries/ queries
foldseek search queries afdb_meta result db_tmp
foldseek convertalis queries afdb_meta result hits.m8 \
  --format-output "query,target,evalue,bits,alntmscore,qtmscore,ttmscore,rmsd,lddt,qcov,tcov,prob"

Memory is the usual constraint at this scale, because the prefilter index for hundreds of millions of structures is large. The Foldseek documentation describes a padded database workflow for exactly this case: build it once with foldseek makepaddeddb afdb_meta afdb_meta_padded, then search the padded database with prefilter-mode set to 1 to cut RAM requirements substantially. Add -compressed 1 when disk is the binding constraint instead.

You can also build custom target libraries. Download mmCIF folders for the accession ranges you care about from the EBI FTP tree, then index them yourself:

foldseek createdb my_afdb_subset/ my_targets

This is the practical route to a taxon-focused or project-focused library that fits on a workstation. Runtime expectations scale accordingly: a PDB-sized search finishes in minutes on a laptop, while the full metagenomic sets are jobs for a server or an HPC node, scheduled with scratch space on local disk and generous time limits.

Checking That a Hit Is Real

A filtered hit list is a hypothesis generator, not an annotation. Run these checks before you commit language to a manuscript or database entry.

1. Recompute the geometry. Confirm the reported TM-score with easy-rmsd or a standalone TM-align run. Agreement between tools rules out an alignment artifact.
2. Look at it. Superpose query and hit in ChimeraX or PyMOL. Conserved hydrophobic cores and connected beta-sheet topology are convincing. Matching secondary structure counts alone are not.
3. Check the sequence and motifs. Extract the aligned sequences (add the qseq and tseq tokens to your format string, or fetch FASTA files from UniProt) and build a multiple sequence alignment with MAFFT. Catalytic residues and ligand-binding motifs in conserved positions upgrade a fold match toward a function claim.
4. Check confidence on both sides. Read the pLDDT profile of your query model and of the AFDB hit over the aligned region, and consult the predicted aligned error (PAE) when interfaces or domain arrangements matter. An alignment between two low-confidence regions is worth very little.
5. Test reciprocity and structure. Search the top hit back against your query set, and cluster your hits with foldseek easy-cluster to see whether they form coherent fold families or a scatter of weak matches.
6. Add evolutionary and genomic context. Follow structure hits with profile searches against curated families, examine the genomic neighborhood on the original metagenomic contig, and place candidates on a phylogeny. The computational viromics literature argues explicitly for pairing AI-driven pattern recognition with classical phylogenetics and functional annotation, precisely because structure-only signals do not carry lineage or mechanism information by themselves [1].

Common Mistakes and Limitations

• Confusing the three services. The AlphaFold Server predicts new structures, the AlphaFold database stores precomputed ones, and the Foldseek server searches. Pointing a search at the prediction server, or expecting the database to fold your sequence, wastes a day.
• Trusting the default result count. With max-seqs at its default of 25, absence of evidence about a fold's rarity means nothing. Raise it before drawing conclusions.
• Ignoring fragments and repeat proteins. Coiled coils, leucine-rich repeats, and transmembrane helix bundles generate recurring weak matches that look impressive in a long list. Coverage filters and a quick visual check remove most of them.
• Searching disordered regions. Low-pLDDT tails adopt whatever conformation minimizes the prediction loss, and Foldseek will happily match that noise to something. Trim before searching.
• Forgetting the single-chain blind spot. AFDB models do not include binding partners, and some folds are only stable inside complexes. For complex questions, predict with the AlphaFold Server and interpret interface confidence with PAE.
• Equating fold similarity with orthology. Some folds recur across unrelated lineages. Corroborate with sequence identity, motif content, and phylogeny before naming a function.
• Porting E-value habits between databases. An E-value that feels stringent against a curated database can be lenient against a billion-prediction metagenomic one. Recalibrate within each search.
• Underestimating resources. The failure modes are predictable, and each has a standard fix:
• bash: foldseek: command not found means the binary is not on your PATH. Re-run the PATH export or activate the conda environment.
• curl: (22) The requested URL returned error: 404 when fetching an AFDB file means a wrong accession or an outdated version suffix. Check the entry page for the current file name.
• No space left on device during a download or search means the target database or scratch directory outgrew its volume. Check with df -h, point the scratch directory at a larger volume, and enable compressed databases.
• Out of memory: Killed process 12345 (foldseek) in the system log means the kernel terminated the job. Rebuild the target with makepaddeddb, search with prefilter-mode 1, or split the target into subsets.
• Ignoring version drift. Model version suffixes and database rebuilds change results between months. Record versions and download dates, or your own reruns will not reproduce your hits.
• Overtrusting AI output in general. Reviews of AI-driven viromics flag computational burden, dataset bias toward characterized families, limited explainability, and elevated false discovery rates as standing problems [1]. Individual projects, and any claim headed toward publication, need review by someone with domain expertise in the protein family involved.

Frequently Asked Questions

Can Foldseek search a raw amino acid sequence against AlphaFold structures?

No. Foldseek aligns structures, so fold the sequence first with ColabFold, the AlphaFold Server, or ESMFold, then search the resulting model. The Foldseek web server can also accept a sequence and handle the folding step for you.

How much hardware does the full metagenomic database need?

Plan for serious hardware. Prebuilt Foldseek copies of the AlphaFold metagenomic sets occupy hundreds of gigabytes to terabytes of disk, and building the search index needs large amounts of RAM. Use the web server, search smaller subsets, or run on a high-memory machine.

What TM-score cutoff should I use for AlphaFold metagenomic hits?

Start at 0.5. TM-scores above 0.5 usually indicate the same fold and scores below about 0.4 usually do not, so treat the range in between case by case, confirmed with coverage, E-value, and visual superposition.

What is the difference between alntmscore, qtmscore, and ttmscore?

They score the same alignment with different normalizations. alntmscore uses the alignment length, qtmscore the query length, and ttmscore the target length, so pick the one that matches the question you are asking.

Does Foldseek need a GPU?

No. Foldseek runs on CPUs and scales with thread count and memory. GPUs matter for the prediction step that produces your query model, not for the search itself.

Can Foldseek search RNA or DNA structures?

Foldseek was built for protein structures. Nucleic acid support is newer and narrower than the protein workflow, so check the current release notes before relying on it for RNA or DNA searches.

How do I cite Foldseek and the AlphaFold database?

Cite van Kempen and colleagues, "Foldseek: fast and accurate protein structure search," Nature Biotechnology, 2023, for the tool, and Varadi and colleagues, Nucleic Acids Research, 2022, for the AlphaFold Protein Structure Database. Add Abramson and colleagues, Nature, 2024, if you use AlphaFold 3 or the AlphaFold Server.

Can I use AlphaFold Server or ColabFold output as a query?

Yes. Both produce PDB or mmCIF models that Foldseek reads directly. Split multimer predictions into single chains before searching, and check pLDDT before trusting low-confidence regions.