ESMFold Tutorial: Predict Protein Structure in Seconds

ESMFold predicts a protein’s 3D structure from its amino acid sequence alone, with no multiple sequence alignment and no database search. You can fold a sequence of up to 400 residues in seconds by posting it to the public ESM Atlas endpoint with a single curl command, which returns a standard PDB file with per-residue confidence in the B-factor column.

Most structure prediction tutorials start by telling you to queue a ColabFold job and wait for an MSA search to finish. That search is often the slowest part of the whole pipeline. ESMFold removes it. Because the model reads the sequence directly through a protein language model, there is nothing to search and nothing to install if you use the public API.

This guide is written by the StemSkills Lab team, who have spent more than ten years in sequence and structural bioinformatics, drug discovery and design, and multiscale molecular modeling. Every command below was run against the live endpoint on 25 September 2026, and every number quoted comes from the published paper or from output you can reproduce yourself.

What is ESMFold, and how does it differ from AlphaFold?

ESMFold is an end-to-end structure predictor built on the ESM-2 protein language model. AlphaFold2 and ColabFold build an evolutionary profile for your protein first, by searching large sequence databases for homologues and assembling a multiple sequence alignment. ESMFold skips that step entirely. The language model has already learned patterns of coevolution during pretraining, so a single sequence is enough input.

The model was published by Lin and colleagues in Science (2023, volume 379, pages 1123 to 1130). The authors describe the result as “an order-of-magnitude acceleration of high-resolution structure prediction”, and they used it to build the ESM Metagenomic Atlas by predicting structures for more than 617 million metagenomic protein sequences, of which more than 225 million were predicted with high confidence.

The speed difference is concrete. The preprint version of the paper reports that on a single NVIDIA V100 GPU, ESMFold predicts a 384-residue protein in 14.2 seconds, about 6 times faster than a single AlphaFold2 model, rising to roughly 60 times faster on shorter sequences. The homology search that AlphaFold2 runs first can take over 10 minutes on its own.

How do you run ESMFold without installing anything?

The fastest route is the public folding endpoint documented in the official facebookresearch/esm repository. Post your raw one-letter sequence to it and save the response as a PDB file.

curl -X POST --data "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG" \
  https://api.esmatlas.com/foldSequence/v1/pdb/ \
  -o result.pdb

Three details matter here. The request body is the bare sequence, with no FASTA header and no newlines. The response is a plain PDB file, not JSON. And the first line of that file reads TITLE ESMFOLD V1 PREDICTION FOR INPUT, which is how you confirm you received a model rather than an error message.

If you prefer a browser, the same model is exposed on the ESM Atlas fold page, where you paste a sequence and download the result.

A worked example you can reproduce

Take human haemoglobin subunit alpha, UniProt accession P69905, which is 142 residues long. Pull the sequence, strip the FASTA header and newlines, then fold it:

curl -s "https://rest.uniprot.org/uniprotkb/P69905.fasta" -o P69905.fa
SEQ=$(grep -v '^>' P69905.fa | tr -d '\n')
curl -X POST --data "$SEQ" https://api.esmatlas.com/foldSequence/v1/pdb/ -o hba.pdb

In our run, that request returned a complete 142-residue model in about 2 seconds. A 400-residue sequence took roughly 28 seconds through the same endpoint. Your timings will vary with server load, but the order of magnitude is the point: this is a coffee-free wait.

If you have not worked with sequence retrieval before, our guides on getting a protein sequence from UniProt and downloading a structure from the RCSB PDB cover the upstream steps.

How do you read ESMFold’s confidence scores?

ESMFold writes per-residue pLDDT confidence into the B-factor column of the PDB file, exactly as AlphaFold does. There is one trap that catches almost everyone, and it is the reason models get thrown away for no reason.

The public API returns pLDDT on a 0 to 1 scale. The local Python model returns it on a 0 to 100 scale. A residue at 0.87 from the API and a residue at 87 from a local run are the same confidence. If you load an API model into a viewer that colours by AlphaFold conventions, every residue will look catastrophically bad, because the viewer expects 70 and 90 as cutoffs.

Here is a one-line check that reports the mean pLDDT over C-alpha atoms:

awk '$1=="ATOM" && $3=="CA" {s+=substr($0,61,6); n++} END {printf "residues=%d mean_pLDDT=%.3f\n", n, s/n}' hba.pdb

Running that on the haemoglobin model above gives residues=142 mean_pLDDT=0.947. Rescaled to AlphaFold’s convention that is 94.7, which sits in the very high confidence band. That is the expected outcome for a small, well-studied, single-domain globular protein.

Interpret the bands the same way you would for AlphaFold, after rescaling:

One difference from AlphaFold worth planning around: the public ESMFold endpoint gives you pLDDT but no PAE matrix, so you cannot assess the relative placement of two domains the way a PAE plot lets you. Our explainer on interpreting pLDDT and PAE scores covers what you lose when PAE is unavailable. Before any downstream work, run the model through the checks in our guide to validating a protein structure.

How do you run ESMFold in Python or on your own GPU?

You need the local route for three situations: sequences longer than 400 residues, batches of many sequences, and anything you cannot send to a third-party server.

Route 1: Hugging Face Transformers

The Transformers port is the least painful install because it bundles the folding dependencies. The official ESM documentation gives the entry point:

from transformers import AutoTokenizer, EsmForProteinFolding

model = EsmForProteinFolding.from_pretrained("facebook/esmfold_v1")
tokenizer = AutoTokenizer.from_pretrained("facebook/esmfold_v1")

Meta also publishes a ready-made protein folding notebook, and ColabFold ships an ESMFold notebook that runs on a free Colab GPU.

Route 2: the original esm package

Installed with the [esmfold] extra, the original implementation exposes a direct inference call:

import torch, esm

model = esm.pretrained.esmfold_v1()
model = model.eval().cuda()
# model.set_chunk_size(128)   # lowers memory use, costs speed

sequence = "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
with torch.no_grad():
    output = model.infer_pdb(sequence)

with open("result.pdb", "w") as f:
    f.write(output)

The same repository ships a batch command line tool, esm-fold, which folds every sequence in a FASTA file. The flags that matter in practice are --num-recycles (default 4, matching training), --chunk-size (recommended values 128, 64 or 32 when you run out of GPU memory), --max-tokens-per-batch, and --cpu-only or --cpu-offload when no GPU is available.

Two practical notes from the official documentation. The esmfold_v1 checkpoint is a 690 million parameter folding trunk on top of a 3 billion parameter ESM-2 stem, so plan for a substantial GPU. And multimers are supported by joining chains with a colon in the input sequence, in both the Python call and the FASTA file.

Is an ESMFold model accurate enough for docking and MD?

Sometimes. The honest answer depends on how far your protein sits from anything the language model has seen, and the paper gives you the numbers to decide.

On the CAMEO test set of 194 structures, ESMFold reaches an average TM-score of 0.83. AlphaFold2, running its full pipeline with MSAs and templates, reaches 0.88 on the same set. On the harder CASP14 set of 51 targets, the gap widens considerably: ESMFold scores 0.68 against AlphaFold2’s 0.85. RoseTTAFold averages 0.82 on CAMEO, so ESMFold is competitive with it on routine targets.

Read that gap carefully. For ordinary, well-represented proteins the two methods land close together. For difficult, remote, or sparsely represented targets, the MSA-based method is clearly better, and that is precisely where a wrong model will waste weeks of docking and simulation time. The Transformers documentation states the condition plainly: ESMFold “has similar accuracy to AlphaFold2 and RoseTTAFold for sequences with low perplexity that are well understood by the language model”.

A workable decision rule for a student project:

• Mean pLDDT above 0.90 and a compact, well-packed fold: proceed to preparation and docking.
• Mean pLDDT 0.70 to 0.90: usable, but refine side chains and treat loop regions as unreliable.
• Mean pLDDT below 0.70, or an orphan sequence with no known relatives: run AlphaFold or ColabFold before committing to any downstream calculation.

Whichever model you take forward, it still needs the standard cleanup: hydrogens, protonation states and missing atoms. Our walkthroughs on preparing a protein and ligand for docking and preparing a protein for molecular dynamics pick up from here.

ESMFold vs AlphaFold vs homology modelling: which should you use?

In a realistic workflow the three are complementary rather than competing. Use ESMFold to triage a list of candidates in minutes, then spend AlphaFold time only on the ones that survive. If a close experimental template exists, our homology modelling tutorial is often the faster and more defensible route, and the trade-offs are laid out in full in our comparison of AlphaFold, homology modelling and experimental structures. For the wider sequence-to-simulation path, see our computational biology skills roadmap.

What errors will you hit, and how do you fix them?

These are the failures we reproduced against the live endpoint, with the exact response text.

HTTP 413: “Sequence is longer than 400.”

The public API refuses anything above 400 residues. There is no queue and no workaround on the endpoint itself. Either fold a defined domain rather than the full-length protein (find the domain boundaries in UniProt), or switch to the local route or a Colab notebook, which have no such cap.

HTTP 422: “Sequence is only allowed to have … tokens.”

The error lists the accepted characters. It accepts the 20 standard amino acids plus the ambiguity codes B, J, Z and X. It rejects digits, asterisks, gaps and lowercase artefacts. This almost always means a FASTA header, a stop codon symbol or a newline made it into the request body. Strip them with grep -v '^>' file.fa | tr -d '\n' before posting.

The PDB file has no TER or END record

Output from the API ends on the last ATOM line. Some parsers and simulation tools object to a file with no terminator. Append one before feeding the model to a pipeline that complains:

printf "TER\nEND\n" >> result.pdb

Every residue looks red in the viewer

This is the 0 to 1 versus 0 to 100 scale problem described above, not a bad model. Check the mean with the awk one-liner before concluding anything. If your tool insists on the AlphaFold scale, multiply the B-factor column by 100.

CUDA out of memory on a local run

The documented remedy is to chunk the axial attention, which reduces memory from quadratic to linear in sequence length. Set model.set_chunk_size(128) in Python, or pass --chunk-size 128 to esm-fold, and step down to 64 or 32 if it still fails. --cpu-offload is the last resort, and it is slow.

Frequently asked questions

Is ESMFold free to use?

Yes. The model weights are released under the MIT license and ESM Metagenomic Atlas data is available under a CC-BY-4.0 license for academic and commercial use, as stated in the header of every PDB file the API returns. Cite the Science paper in any work you publish.

Can ESMFold predict protein complexes?

It supports multimer input by joining chains with a colon, but complex prediction is not what it was benchmarked for, and results are less reliable than for single chains. For genuine complexes, AlphaFold-Multimer through ColabFold is the better tool.

Does ESMFold model ligands, ions or cofactors?

No. It predicts the protein backbone and side chains from sequence only. Any ligand, metal or cofactor has to be placed afterwards by docking or by superimposing a holo template.

Why is my predicted structure mostly loops and coils?

Low pLDDT across long stretches usually means the region is intrinsically disordered rather than that the prediction failed. Check the sequence for low-complexity regions before assuming an error, and consider trimming disordered tails before docking or simulation.

Should I still learn AlphaFold if ESMFold is this fast?

Yes. AlphaFold remains more accurate on hard targets, provides the PAE matrix that ESMFold’s API does not, and is what reviewers expect to see in a methods section. Our AlphaFold prediction tutorial covers that route, and the full sequence of skills is mapped in the skills roadmap.