# Foldseek AlphaFold Search Tutorial: Step-by-Step Guide By the end of this foldseek alphafold search tutorial you will be able to install Foldseek, turn any [protein structure](/blog/guides/protein-structure) file into a searchable query, run that query against the AlphaFold database and its more than 200 million predicted structures, and read the resulting table of hits with enough fluency to defend your interpretation in a paper, a thesis chapter, or a production pipeline. You will also learn how to sanity-check your setup, tune sensitivity, and avoid the errors that waste the most time. Here is what you need on hand before starting: - A Linux machine, a Mac, or Windows with WSL2 (Windows Subsystem for Linux). - At least 8 GB of RAM for the tutorial steps. Batch searches against the full AlphaFold database benefit from 64 GB or more. - About 1 GB of free disk space for the worked examples. The full AlphaFold database download is measured in terabytes, covered in Step 4. - Comfort with a terminal. No prior structural bioinformatics experience is assumed. ## What Foldseek Does and Why It Suits AlphaFold Data Foldseek is an open-source tool for fast protein structure search, published in Nature Biotechnology in 2023 by van Kempen and colleagues from the Söding and Steinegger labs. Classical structural aligners such as TM-align and DALI compare structures residue pair by residue pair, which produces excellent alignments but takes minutes per pair. That is fine for comparing two proteins and hopeless for scanning a database of 200 million models. Foldseek solves the speed problem with the 3Di alphabet. Every residue in a structure gets a single letter (one of 20) that encodes the local geometry of the backbone around that residue. A structure therefore becomes a string of structural letters, and a structure-vs-structure comparison becomes a sequence-like lookup that reuses the fast prefiltering ideas of MMseqs2, the widely used sequence searcher from the same lab. During the alignment stage, Foldseek scores the 3Di letters together with the amino acids, which recovers most of the alignment quality of slow structural aligners at a tiny fraction of the cost. In published benchmarks it reaches accuracy comparable to TM-align while being orders of magnitude faster. That speed is what makes the AlphaFold database searchable at all. The AlphaFold Protein Structure Database, hosted by EMBL-EBI, contains predicted models for more than 200 million UniProt proteins, effectively the proteomes of thousands of species. A structure search against that resource can reveal remote homology that sequence methods such as BLAST miss entirely, because two proteins can share a fold while their sequences have diverged beyond recognition. ## Where to Run Your Search: Web Server, API, or Local Install There are three ways to run a Foldseek search against AlphaFold data, and the right choice depends on scale. The Foldseek web server at search.foldseek.com accepts an uploaded PDB or mmCIF file, or a plain [amino acid sequence](/blog/guides/amino-acid-sequence) that the server predicts into a structure first, and searches it against AlphaFold, the PDB, and other prebuilt targets. It shows alignments in an interactive viewer and is the fastest route for one-off questions. Results are stored for a limited period, so download anything you want to keep. The same server exposes a documented REST API for scripted submissions. A local installation is the better choice when you need reproducibility, custom parameters, large query batches, or the ability to work offline. The rest of this tutorial covers the local workflow in depth, because every parameter that matters is only visible and controllable there. ## Installing Foldseek Three installation paths cover essentially every setup. Pick one. ### Option 1: Conda or Mamba If you use conda, install from the bioconda channel: ```bash conda install -c bioconda foldseek ``` This is the simplest option and handles updates with `conda update foldseek`. ### Option 2: Static Binary Foldseek publishes self-contained static builds. On Linux with a modern x86 CPU: ```bash wget https://mmseqs.com/foldseek/foldseek-linux-avx2.tar.gz tar xvzf foldseek-linux-avx2.tar.gz export PATH="$(pwd)/foldseek/bin:$PATH" ``` The avx2 build uses advanced CPU instructions for speed. For older CPUs, the same download page offers an sse2 build, and a dedicated GPU build for NVIDIA cards is also available. On macOS, grab the universal build from the same page (foldseek-osx-universal.tar.gz at the time of writing), which covers both Apple silicon and Intel machines. ### Option 3: Docker ```bash docker pull ghcr.io/soedinglab/foldseek:latest docker run --rm -it -v "$PWD:/data" ghcr.io/soedinglab/foldseek:latest foldseek version ``` Mount your working directory (the `-v "$PWD:/data"` part) so the container can read your files and write results back. ### Verify the Install ```bash foldseek version ``` You should see a version string and a build date. If you see `bash: foldseek: command not found`, the binary directory is not on your PATH. Re-run the `export PATH` line from Option 2, or activate the conda environment you installed into. ## Understanding AlphaFold Models Before You Search Think of this section as a compact alphafold tutorial for the database side of the workflow, because interpreting a search against predicted structures requires knowing what those structures are. AlphaFold is a deep learning system that predicts a protein 3D structure from its amino acid sequence. The AlphaFold Protein Structure Database, maintained by EMBL-EBI in collaboration with Google DeepMind, stores one predicted model per UniProt entry. UniProt is the standard curated [protein sequence database](/blog/guides/protein-sequence-database), and a proteome is the complete set of proteins produced by one organism. Each model ships as an mmCIF file (the modern community standard for structural data) with per-residue confidence attached. The key metric is pLDDT, a per-residue score from 0 to 100 that estimates how well the local structure is determined. The convention from the AlphaFold documentation divides models into four bands: above 90 is very high confidence, 70 to 90 is confident for backbone positions, 50 to 70 is low confidence, and below 50 is very low confidence and frequently marks intrinsically disordered regions. In the distributed files, pLDDT values are stored in the B-factor column, which is why structure viewers color AlphaFold models by confidence automatically. A second metric, PAE (predicted aligned error), describes how confident the model is about the relative positions of residues or chains, and is available as a separate download. Two consequences matter for searching. First, low-pLDDT tails are not reliable structures, and alignments that land in them are noise. Second, these are predictions, not experiments. They contain no ligands, cofactors, or post-translational modifications, and each entry is a single conformation rather than the ensemble an experiment might reveal. ## Foldseek AlphaFold Search Tutorial: Step-by-Step Walkthrough ![Flow from getting a query structure through building databases, searching, and converting results to a readable table.](/article-images/illustrations/foldseek-alphafold-search-tutorial-local-search-steps.webp) This walkthrough uses ubiquitin as the running example. Ubiquitin is a small 76-residue protein with an extremely well-characterized structure, which makes it easy to judge whether results make sense. Every command below runs from a fresh working directory. ### Step 1: Get a Query Structure ```bash mkdir foldseek-tutorial && cd foldseek-tutorial mkdir queries wget https://files.rcsb.org/download/1UBQ.pdb -P queries/ ``` 1UBQ is the crystal structure of bovine ubiquitin from the RCSB [Protein Data Bank](/blog/guides/protein-data-bank) (PDB), the public archive of experimentally determined structures. Foldseek reads standard PDB and mmCIF files, so you can equally drop in your own cryo-EM model, an AlphaFold prediction downloaded from the EMBL-EBI site, or an AlphaFold Server output (covered near the end of this guide). One formatting detail to know: Foldseek treats each protein chain as its own searchable unit and appends the chain identifier to the name. Your query will appear in results as `1UBQ_A`. ### Step 2: Build the Query Database ```bash foldseek createdb queries/ queryDb ``` `createdb` parses the coordinates, computes the 3Di string for every residue, and writes a set of companion files sharing the prefix `queryDb` (indexes plus coordinate and 3Di data). Point it at a directory and every structure file inside becomes part of the database, so the same command scales from one file to thousands. ### Step 3: Smoke Test on a Tiny Target Set Before committing to a terabyte-scale download, confirm the whole pipeline works on a toy target database. Download two more PDB entries, one clear homolog of ubiquitin and one unrelated protein: ```bash mkdir targets wget https://files.rcsb.org/download/1D3Z.pdb -P targets/ wget https://files.rcsb.org/download/1HHO.pdb -P targets/ foldseek createdb targets/ targetDb foldseek search queryDb targetDb toy_result tmp foldseek convertalis queryDb targetDb toy_result toy_hits.tsv \ --format-output "query,target,evalue,bits,fident,alntmscore,qtmscore,ttmscore,rmsd,prob" ``` 1D3Z is a solution NMR structure of human ubiquitin. 1HHO is human oxyhemoglobin, whose fold shares nothing with ubiquitin. Expect output shaped like this (your exact numbers will differ slightly): ``` query target evalue bits fident alntmscore qtmscore ttmscore rmsd prob 1UBQ_A 1D3Z_A 2.7e-33 151 1.000 0.997 0.997 0.996 0.31 1.00 ``` The homolog appears with a near-perfect TM-score and a vanishing e-value. Hemoglobin is absent, which is exactly what a correct pipeline should produce. If you see a hemoglobin hit above the ubiquitin hit, stop and debug before going further. A second sanity check that catches most setup problems is the self-hit test: ```bash foldseek easy-search queries/ queries/ selfcheck.tsv tmp ``` Searching a database against itself must return each structure as its own top hit with an `alntmscore` of 1.0. If it does not, the coordinates were not parsed correctly, often because the file contains no usable ATOM records. ### Step 4: Download the AlphaFold Database Foldseek ships prebuilt versions of the major structure databases: ```bash foldseek databases Alphafold afdb afdb_tmp ``` This downloads the full AlphaFold database and converts it into Foldseek's internal format under the prefix `afdb`, using `afdb_tmp` as scratch space. Three practical points: 1. **Size.** The full database is measured in terabytes. The Foldseek documentation lists the current size for each prebuilt database, so check it and your free space before starting. Put the temporary directory on the largest disk you have. 2. **The smaller subset.** For many projects, the proteome-restricted subset is enough and far cheaper to store: ```bash foldseek databases Alphafold-proteomes afdbp afdbp_tmp ``` 3. **Other targets.** The `databases` help text and the Foldseek website list every prebuilt option, including the PDB and the ESM Metagenomic Atlas of predicted metagenomic structures. The download takes hours depending on bandwidth. Once it finishes, the `afdb_tmp` scratch directory can be deleted. ### Step 5: Run the Search ```bash foldseek search queryDb afdb afdb_result afdb_search_tmp --threads 16 -s 9.5 -e 0.001 ``` The four positional arguments are the query database, the target database, an output result database, and a scratch directory. The result database is an internal binary format, not something you read directly, which is why Step 6 exists. The options that matter most: | Option | What it controls | Sensible starting point | |, - |, - |, - | | `-s` | Search sensitivity. Higher values find more distant relatives at a steep runtime cost. | 9.5 (the default). Raise toward 10 to 11 for remote homolog hunts. | | `-e` | E-value threshold for reporting a hit. | 0.001 (the default). Loosen to 0.01 for exploratory scans. | | `-max-seqs` | Maximum reported alignments per query. | 500 to 1,000 when browsing. Keep lower for very large batches. | | `-cov-mode` and `-cov` | Which length coverage is measured against, and the minimum coverage fraction. | `-cov-mode 2, cov 0.7` requires most of the query to be aligned. Check `foldseek search -h` for the exact semantics of your version. | | `-min-seq-id` | Minimum sequence identity filter. | Leave at 0. Structure similarity is the signal you are chasing. | | `-threads` | CPU threads used. | All physical cores on the machine. | | `-format-output` | Columns written by `convertalis`. | See Step 6. | A single query against the full AlphaFold database typically finishes in minutes on a multicore server. Batch searches scale roughly linearly with query count. ### Step 6: Convert Results to a Readable Table ```bash foldseek convertalis queryDb afdb afdb_result afdb_hits.tsv \ --format-output "query,target,evalue,bits,fident,alntmscore,qtmscore,ttmscore,rmsd,qstart,qend,qlen,tstart,tend,tlen,prob" ``` This writes a tab-separated file. The columns worth knowing: | Column | Meaning | |, - |, - | | `query`, `target` | Chain identifiers of the query and the matched database entry. | | `evalue` | Expectation value. The number of hits with a score at least this good you would expect by chance in a database of this size. Lower is stronger. | | `bits` | Bit score, a log-scaled measure of alignment quality. Higher is stronger. | | `fident` | Fraction of identical residues in the alignment, from 0 to 1. | | `alntmscore` | TM-score of the alignment. A structural similarity measure from 0 to 1 that is normalized for length, so unlike RMSD it stays comparable across alignments of different sizes. | | `qtmscore`, `ttmscore` | The same TM-score normalized by the query length and the target length respectively. | | `rmsd` | Root-mean-square deviation of the aligned atoms in angstroms. Lower is better, but the value depends on how many residues were aligned. | | `qstart`, `qend`, `qlen` | Aligned span on the query and the query's total length. | | `tstart`, `tend`, `tlen` | Aligned span on the target and the target's total length. | | `prob` | Foldseek's estimated probability, from 0 to 1, that the hit is a true homolog rather than a chance match. | ### Step 7: The One-Command Alternative `easy-search` chains database creation, search, and conversion into a single call, which is convenient for quick analyses: ```bash foldseek easy-search queries/ afdb afdb_easy_hits.tsv tmp \ --format-output "query,target,evalue,alntmscore,qtmscore,ttmscore,rmsd,prob" -s 9.5 ``` The query can be a single file, a directory of files, or a database prefix, and the target can be any database you built or downloaded. Under the hood it runs the same algorithm as Steps 2 through 6. Use `easy-search` for exploration and the split commands when you want to reuse a query database for many different targets or rerun conversion with different output columns without redoing the search. ### Step 8: Interpret the Hits ![Formula for query coverage with the worked ubiquitin example giving 57 over 76, about 0.75.](/article-images/illustrations/foldseek-alphafold-search-tutorial-query-coverage.webp) Read the columns in a fixed order and the table becomes easy to judge. Start with `alntmscore`. The widely used convention from the TM-score literature is that a TM-score above 0.5 indicates the two proteins share the same fold, while values approaching 1.0 indicate near-identical topology. Values between roughly 0.3 and 0.5 sit in a gray zone where fold-level similarity is suggestive but not conclusive. For a ubiquitin query against the AlphaFold database, expect a wall of near-1.0 hits from ubiquitin itself across species, then a long tail of ubiquitin-like domains from the beta-grasp fold family with scores sliding down through the 0.5 to 0.7 range. Next check coverage, because a high TM-score on a tiny aligned fragment means little. Compute query coverage from the coordinate columns: ``` query_coverage = (qend - qstart + 1) / qlen ``` Worked example: a hit with `qstart` 5, `qend` 61, and `qlen` 76 covers `(61 - 5 + 1) / 76 = 57 / 76 ≈ 0.75` of the query. Decide whether 75 percent coverage answers your question. If you care about the whole domain, require high coverage with `-cov-mode 2, cov 0.7`. If you are hunting for a shared subdomain, partial coverage is the point. Then read `evalue` and `prob` together. An e-value below roughly 0.01 against a database this size is strong evidence of relatedness, and a `prob` near 1.0 reinforces it. Remember that e-values depend on database size, so an e-value from a search against AlphaFold is not directly comparable to one from a search against the PDB. Finally, ignore `fident` as a filter. The entire reason to run a structure search is that meaningful structural matches can have sequence identity near zero. Filtering hits by `fident` throws away exactly the discoveries the method exists to find. ### Step 9: Look at the Alignments Numbers convince reviewers, pictures convince everyone. Two routes: 1. **Superposition matrices from Foldseek.** Add `u,t` to your `-format-output` list. These columns carry the rotation and translation that superimpose the aligned pair, which lets you reproduce the superposition programmatically. 2. **A molecular viewer.** Load the query and the top hit in ChimeraX or PyMOL and superimpose: ```text open 1ubq.pdb open af_hit_model.cif matchmaker #1 to #2 ``` In PyMOL the equivalent is the `align` command. Inspect whether the aligned core really matches and whether the differences cluster in low-confidence regions. Sensible next steps after a successful search: cluster your hits with `foldseek easy-cluster` to organize them into families, pull representative hit structures from the AlphaFold database site for deeper analysis, or feed the alignment columns into downstream scripts for phylogeny or annotation transfer. ## Tips for Faster, More Sensitive Foldseek Searches These are the adjustments that change results the most in practice. **Raise sensitivity only when you need it.** The default `-s 9.5` is a good speed-accuracy balance. When you suspect a remote relationship that the default run missed, rerun with `-s 10` or higher. Each increment costs runtime, so tune on a small query set first. **Use the proteome subset for triage.** A first pass against `Alphafold-proteomes` returns most of what most projects need at a fraction of the storage and time. Reserve the full `Alphafold` database for exhaustive sweeps. **Trim low-confidence regions from AlphaFold queries.** Disordered tails generate spurious matches because their coordinates are essentially arbitrary conformations. Since pLDDT lives in the B-factor column, you can strip weak residues in PyMOL: ```text load my_model.cif remove b < 70 save my_model_trimmed.cif ``` Search the trimmed model and report in your methods that residues below pLDDT 70 were removed. **Calibrate with a self-hit.** Any time you change databases, parameters, or Foldseek versions, run one query against itself. A self-hit with `alntmscore` 1.0 confirms the pipeline end to end in seconds. **Keep scratch space local.** Point every temporary directory at a fast local SSD. Network filesystems and cloud-synced folders slow the prefilter dramatically and can corrupt long-running jobs. **Scale deliberately.** For thousands of queries, split the query database into chunks and run them sequentially or across nodes. If you repeatedly search the same target database, look at `foldseek makepaddeddb`, which pre-processes a target for faster repeated searches. If you have an NVIDIA GPU, the GPU build enabled with `-gpu 1` accelerates large searches substantially. **Record your versions.** Write the output of `foldseek version` and the database download date into your methods or your pipeline log. Structure databases change, and a result table without those two facts is hard to reproduce. ## Common Mistakes and Limitations These are the failures seen most often, with the exact symptoms and fixes. **Running the binary without fixing PATH.** Symptom: `bash: foldseek: command not found` immediately after a manual install. Fix: export the `foldseek/bin` directory into PATH, or add the export line to your shell profile so it survives new terminals. **Wrong binary for the CPU.** Symptom: `Illegal instruction (core dumped)` the moment any command runs. This happens when the avx2 build runs on a CPU without AVX2 support. Fix: download the sse2 build instead. **Disk exhaustion during the database download.** Symptom: `No space left on device` partway through `foldseek databases`. The full AlphaFold database is terabytes, and the scratch directory needs room too. Fix: check the documented size beforehand, prefer `Alphafold-proteomes` when it suffices, and place both the database and the temporary directory on a volume with enough free space. **Out of memory during large batch searches.** Symptom: the process disappears and `dmesg` shows the kernel OOM killer logging a `Killed` event. Fix: split the query database into smaller chunks, reduce concurrency, or move to a machine with more RAM. **Confusing the scratch directory with the database prefix.** `foldseek databases Alphafold afdb afdb_tmp` creates the database at the prefix `afdb`. Passing `afdb_tmp` as the search target fails or behaves unpredictably. The target argument for `search` and `easy-search` is always the database prefix, not the temporary folder. **Filtering hits by sequence identity.** As explained in Step 8, low `fident` is expected and often is the interesting case. Filter on `alntmscore`, coverage, and `evalue` instead. **Trusting short high-scoring fragments.** TM-score is length-normalized, but a 15-residue alignment with a high score can still be a coincidence inside a loop. Always read `alntmscore` next to the aligned span and coverage before believing a hit. **Searching through disordered tails.** Alignments that fall in pLDDT-below-50 regions of AlphaFold models carry no structural meaning. Trim or discount them. **Comparing e-values across different target databases.** E-values scale with search space. A 1e-10 hit against the PDB and a 1e-10 hit against AlphaFold represent different amounts of evidence. Compare TM-scores across databases, not e-values. **Treating predictions as measurements.** AlphaFold entries are computational models. They omit ligands, alternate conformations, and environmental context, and their confidence varies residue by residue. Use them as hypotheses that experimental structures or experiments can confirm. On limitations of the method itself: Foldseek searches protein chains, one chain at a time, so complex interfaces are not scored as units, and nucleic acids are outside the 3Di representation. Very unusual folds can still be missed at default sensitivity. And like any similarity tool, a hit supports a hypothesis about homology or fold similarity, it does not prove function. Individual analyses still need domain expertise to interpret responsibly. ## Working with the AlphaFold Server and the AlphaFold Database Two different resources are casually called the AlphaFold server, and a complete workflow often uses both. The first is the AlphaFold Protein Structure Database at EMBL-EBI. Search by UniProt accession, gene name, or organism, inspect the model colored by pLDDT, and download the mmCIF file for local analysis. Bulk downloads of whole proteomes are also provided for compute-heavy projects, though for Foldseek purposes the `foldseek databases` route in Step 4 is simpler because the data arrives already converted. The second is AlphaFold Server, Google DeepMind's free web service for running AlphaFold 3 predictions. You submit sequences, including protein complexes with nucleic acids and ligands, and receive a set of ranked predicted models with confidence scores including pLDDT and PAE. Access is free for non-commercial use, subject to a daily job quota and the posted terms of service. This matters for a search workflow because it closes the loop when your protein has no structure anywhere: predict it with AlphaFold Server, download the resulting mmCIF, and use it as a Foldseek query: ```bash foldseek easy-search af3_model.cif afdb af3_hits.tsv tmp \ --format-output "query,target,evalue,alntmscore,qtmscore,ttmscore,rmsd,prob" ``` For complex predictions, remember from the limitations section that Foldseek treats each chain independently, so search the chain you care about and use the PAE matrix, not the search result, to judge inter-chain confidence. ## Frequently Asked Questions ### Can I search the AlphaFold database without installing Foldseek? Yes. The web server at search.foldseek.com searches uploaded structure files, or sequences it predicts first, against the AlphaFold database directly in your browser. Install Foldseek locally only when you need custom parameters, large batches, or reproducible pipelines. ### What TM-score cutoff means the same fold? The standard convention is that a TM-score above 0.5 indicates the same fold, and values near 1.0 indicate nearly identical topology. Always read the score alongside alignment coverage, because a high score on a tiny fragment is weak evidence. ### Why do my top AlphaFold hits have almost no sequence identity? That is the expected result, not an error. Structure converges more slowly than sequence, so proteins can retain a detectable common fold after their sequences have diverged beyond the reach of BLAST. Low sequence identity with a high TM-score is often the most interesting kind of hit. ### How do I search a protein sequence instead of a structure file? On the web server, paste the sequence and the server predicts a structure before searching. Locally, predict a structure yourself with a tool such as AlphaFold or ColabFold, then use the resulting mmCIF as your Foldseek query. Foldseek itself requires coordinates, not raw sequence. ### How much disk space does the AlphaFold database need? The full database is measured in terabytes, and the downloader also needs temporary space during conversion. The `Alphafold-proteomes` subset is far smaller and adequate for many projects. Check the sizes listed in the Foldseek documentation before you start. ### How do I update my local AlphaFold database copy? Re-run the same `foldseek databases` command with a fresh output prefix whenever the upstream database announces an update, then point your searches at the new prefix. Record the download date with your results for reproducibility. ### Does Foldseek search protein complexes or single chains? Foldseek indexes and searches individual protein chains. A complex file is split into its chains, and each chain is matched independently. To evaluate whether two complexes interact the same way, combine chain-level hits with interface analysis and PAE information rather than relying on the search score alone. ### Can I use AlphaFold Server predictions as Foldseek queries? Yes. Download the predicted mmCIF from AlphaFold Server, optionally trim residues with low pLDDT, and run it as a query against the AlphaFold database or the PDB. This predict-then-search strategy finds structural relatives for proteins that have no experimental structure.