Foldseek Tutorial: Find Structurally Similar Proteins
Skip to content

Foldseek Tutorial: Find Structurally Similar Proteins

Foldseek Tutorial: Find Structurally Similar Proteins

Foldseek is a free tool from the Steinegger and Söding groups that searches a protein structure against databases such as the PDB and the AlphaFold Database and returns structurally similar proteins, even when sequence identity is too low for BLAST. Upload a PDB or mmCIF file at search.foldseek.com, or run foldseek easy-search query.pdb targetDB aln tmp, then rank hits by E-value, probability and TM-score.

This tutorial covers both routes: the web server for a single model, and the command line for repeated or batch searches. It explains the alignment modes, the output columns you actually need, how to turn hits into templates or a function hypothesis, and the input mistakes that make a search come back empty. It is written by the StemSkills Lab team, who have more than ten years of experience in structural bioinformatics, homology modelling and drug design.

When should you use Foldseek instead of BLAST?

Use BLAST first. If your sequence has a clear homolog with a known structure, you already have a template and a likely function. Foldseek earns its place in the other case: your AlphaFold, ESMFold or homology model has no convincing sequence hit, or only hits annotated “uncharacterized protein”. Protein structure is conserved much longer than sequence, so two proteins that share a fold and a common ancestor can sit below 20% sequence identity, where sequence searches stop being reliable.

Classic structural aligners such as Dali and TM-align can detect those relationships, but they are far too slow to scan the hundreds of millions of predicted structures that now exist. Foldseek solves this by translating each residue’s local tertiary contacts into a letter of a 20-state structural alphabet called 3Di, then searching those 3Di strings with fast sequence-search machinery borrowed from MMseqs2. The paper by van Kempen et al., Nature Biotechnology 42:243-246 (2024) reports that “Foldseek decreases computation times by four to five orders of magnitude with 86%, 88% and 133% of the sensitivities of Dali, TM-align and CE, respectively.” In practice, a database search that would be impractical with TM-align finishes in seconds to minutes.

How does Foldseek compare with Dali, TM-align and BLAST?

ToolInputWhat it comparesSpeed on large databasesBest use for a student
BLASTpSequenceAmino acid sequenceFastFirst check for homologs and templates
FoldseekStructure (PDB/mmCIF), or FASTA via ProstT53Di structural alphabet plus amino acidsFast, built for AlphaFold DB scaleFinding remote structural relatives of a model
Dali serverStructureIntramolecular distance matricesSlowA careful second opinion on a short list
TM-alignTwo structuresGlobal residue superposition (TM-score)Pairwise onlyScoring one model against one chosen structure

The usual workflow combines them: Foldseek to find candidates across millions of structures, then TM-align to score your model against the best two or three and report one defensible number. This search step fits the structure stage of our computational biology skills roadmap, between predicting a structure and preparing it for docking.

How do you run a Foldseek search on the web server?

The web server at search.foldseek.com needs no installation or account. A typical run on one AlphaFold model looks like this:

  1. Prepare one chain. Foldseek’s standard search expects single-chain structures. If your file holds a complex, save only the chain you care about (in PyMOL: save chainA.pdb, chain A). Multi-chain searches use a separate complex mode.
  2. Trim very low-confidence regions. Long disordered tails with pLDDT below 50 have no defined structure to match and can dilute the alignment. Our guide to reading pLDDT and PAE shows how to identify them.
  3. Upload the file. Drag the PDB or mmCIF file into the query box, or paste its contents.
  4. Pick databases. The server offers several, including the PDB (listed as PDB100), AlphaFold/UniProt50, AlphaFold/Swiss-Prot, AlphaFold/Proteome, CATH50 and MGnify-ESM30. For template hunting, keep PDB100 selected, since only experimental structures make citable templates. Add AlphaFold/Swiss-Prot when you want hits with curated UniProt annotation.
  5. Choose the mode. Leave the default 3Di/AA mode for the first search. Switch to TM-align mode when you want globally aligned hits ranked by TM-score (explained below).
  6. Read the results per database. Each hit shows the target, its organism where available, a homology probability, sequence identity, E-value and the aligned query and target positions. Click a hit to see the superposition in the browser, and note the scores of every hit you plan to discuss.

Want the guided, hands-on version?

Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.

Join the waitlist (free) →

How do you install Foldseek and run easy-search on the command line?

The command line is worth learning when you need to search many models, search a local folder of structures, or record exact parameters for a methods section. The official Foldseek GitHub README lists precompiled binaries and a conda package:

# Conda (Linux and macOS)
conda install -c conda-forge -c bioconda foldseek

# or the Linux AVX2 binary
wget https://mmseqs.com/foldseek/foldseek-linux-avx2.tar.gz
tar xvzf foldseek-linux-avx2.tar.gz
export PATH=$(pwd)/foldseek/bin/:$PATH

# or macOS
wget https://mmseqs.com/foldseek/foldseek-osx-universal.tar.gz
tar xvzf foldseek-osx-universal.tar.gz
export PATH=$(pwd)/foldseek/bin/:$PATH

Next, download a target database. The databases command fetches prebuilt sets, and the PDB is the sensible first choice on a laptop:

foldseek databases PDB pdb tmp

Other supported names include Alphafold/UniProt50, Alphafold/Swiss-Prot, Alphafold/Proteome and ESMAtlas30. Check memory before you download a large one. The README gives the RAM cost as 8 bytes per database residue (6 for Cα coordinates, 1 for 3Di, 1 for the amino acid) and notes that the 54 million AFDB50 entries need 151 GB. That is a cluster job, not a laptop job, so use the web server for AlphaFold DB searches.

Now run the search. easy-search takes a query (a file or a folder), a target (a database, a folder, or single files), an output file and a temporary directory:

foldseek easy-search model.pdb pdb aln.m8 tmp

To compare your model against a folder of structures you collected yourself, point the target at the folder: foldseek easy-search model.pdb my_structures/ aln.m8 tmp. If you will search the same folder repeatedly, build a database once with foldseek createdb my_structures/ targetDB and search targetDB instead.

Should you use the 3Di+AA or the TM-align alignment type?

The --alignment-type flag controls how hits are aligned and scored. The README documents four values:

ValueMethodScopeWhen to use it
03Di only, Gotoh-Smith-WatermanLocalNot recommended by the authors
1TMalignGlobal, slowRanking whole-chain matches by TM-score
2 (default)3Di+AA, Gotoh-Smith-WatermanLocalThe first search: remote relatives and shared domains
3LoLalignLocal, slowProbabilistic realignment of hits, the newest option

Start with the default. A local alignment can find a single shared domain inside a large multidomain protein, which is exactly what you want when assigning function. Switch to TM-align mode when you need hits that match your whole chain, for example when choosing a full-length template:

foldseek easy-search model.pdb pdb aln_tm.m8 tmp --alignment-type 1

One detail catches people out. In TM-align mode, the README states that results are sorted by the TM-score normalised by query length, and the column normally holding the E-value instead holds the average of the query- and target-normalised TM-scores. Do not read that column as an E-value in this mode.

How do you read Foldseek output: E-value, prob, bits and TM-score?

The default tab-separated output has twelve columns: query, target, fident, alnlen, mismatch, gapopen, qstart, qend, tstart, tend, evalue, bits. That is enough to rank hits but not to judge them. Ask for the structural scores explicitly with --format-output, and add --format-mode 4 to get a header row:

foldseek easy-search model.pdb pdb aln.tsv tmp \
  --format-mode 4 \
  --format-output "query,target,fident,alnlen,qstart,qend,tstart,tend,evalue,bits,prob,alntmscore,qtmscore,ttmscore,lddt"

Here is what each score tells you:

  • evalue: the number of hits this good you would expect by chance in a database of this size. Lower is better. The default cutoff is -e 0.001, so only fairly confident hits appear unless you raise it.
  • bits: the alignment score, independent of database size. Use it to compare hits within one search.
  • prob: the README defines it as the “estimated probability for query and target to be homologous”. It is the most intuitive column for a thesis: a hit near 1 is very likely a true relative.
  • alntmscore, qtmscore, ttmscore: TM-scores normalised by alignment, query or target length. A TM-score above 0.5 generally means the same fold, and below 0.2 corresponds to unrelated proteins, according to the official TM-align documentation.
  • lddt: the average local distance difference test score over aligned residues, a superposition-free measure of local agreement.
  • fident: fraction of identical residues in the aligned region. A hit with high prob and low fident is the remote homolog Foldseek exists to find.

A worked reading: a hit with evalue 1e-12, prob 1.00, qtmscore 0.78 and fident 0.18 is a confident same-fold relative that BLAST would likely have missed. A hit with evalue 0.0008, prob 0.35 and qtmscore 0.32 is a weak local match, perhaps one shared helix bundle, and should not be called a homolog without more evidence.

How do you use Foldseek hits to choose templates or infer function?

For templates, filter to PDB hits with high prob and high qtmscore, then apply the same checks you would for any template: resolution, coverage of your region, bound ligands and oligomeric state. Our guide to template selection for homology modelling walks through those criteria, and the SWISS-MODEL tutorial shows how to supply a chosen template.

For function, look for agreement rather than a single top hit. If most of your confident hits belong to one enzyme family, a function from that family is a reasonable hypothesis. Then check whether the catalytic residues of the hits align with conserved residues in your model; superimposing the pair in PyMOL (see how to superimpose two proteins) makes this quick. Write the result as a hypothesis supported by structural similarity, not as an established function.

For reporting, record the Foldseek version (foldseek version), the database and its date, the alignment type, the E-value cutoff and the scores of each hit you discuss, and cite the Nature Biotechnology paper.

Why does my Foldseek search return no hits or wrong hits?

SymptomLikely causeFix
No hits at allThe 0.001 E-value cutoff is too strict for a genuinely remote proteinRerun with -e 10 and judge hits by prob and TM-score; also try --exhaustive-search, which skips the prefilter
Hits only to a tail or linkerDisordered low-pLDDT regions are being alignedTrim residues with pLDDT below 50 and search again
Results mix several unrelated familiesThe query holds more than one chain, or a multidomain proteinSearch one chain; split domains using the PAE plot and search each
Errors reading the fileMalformed PDB, for example a hand-edited file with shifted columnsRe-save the structure from PyMOL or ChimeraX, or use mmCIF
TM-score columns unavailableTarget database was built from FASTA with ProstT5, which stores no Cα coordinatesUse a structure-based database; the README notes ProstT5 databases do not support TM-score or LDDT output
Download fails or the disk fillsLarge AlphaFold databases and a small temporary directoryStart with the PDB database and point tmp at a disk with free space

Frequently asked questions

Is Foldseek free to use?

Yes. The web server at search.foldseek.com is free and needs no login, and the software is open source on GitHub with conda and precompiled binaries for Linux and macOS.

Can Foldseek search with only a protein sequence?

Yes, in two ways. You can predict a structure first with AlphaFold or ESMFold and search that, or build a database from FASTA with the ProstT5 language model, which predicts 3Di strings directly. The ProstT5 route is faster but cannot report TM-score or LDDT.

What is a good Foldseek E-value?

Lower is better, and the default reporting cutoff is 0.001. Do not rely on E-value alone; check that prob is close to 1 and the TM-score is above 0.5 before calling two proteins the same fold.

What is the difference between Foldseek and TM-align?

Foldseek searches one structure against millions very quickly using a structural alphabet. TM-align carefully aligns exactly two structures and gives a TM-score. Use Foldseek to find candidates and TM-align to score the final comparison you report.

Does Foldseek work on protein complexes?

The standard easy-search is for single chains. Foldseek includes a separate easy-multimersearch module for multi-chain complexes, described in the Foldseek-Multimer paper in Nature Methods (2025).

Foldseek turns a model with no obvious relatives into a short list of real structures you can align, compare and cite. If you want to practise this inside a full modelling, docking and MD workflow, with feedback on each step, the bootcamp is built around exactly that sequence.

Want the guided, hands-on version?

Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.

Join the waitlist (free) →

Think you know Protein Structure Prediction?
Take the free StemSkills assessment and earn a verifiable certificate you can download and add to your LinkedIn profile.
Start the free assessment

Keep going

TM-align Tutorial: Compare Protein Structures by TM-score Install TM-align, compare a predicted model with an experimental structure, read both TM-scores correctly and see why RMSD… CABS-flex 3.0 Tutorial: Protein RMSF Without GROMACS Run a free CABS-flex 3.0 job, pick the right flexibility mode, read the RMSF plot and 10 models,… Periodic Image Check in GROMACS: gmx mindist -pi Prove your protein never touched its own periodic image: run gmx mindist -pi, read the xvg against your…
See live workshops