ESMFold: Install, Run and Read pLDDT (fair-esm and Hugging Face)

ESMFold is a protein structure prediction model from Meta AI’s ESM team that predicts a three-dimensional structure from a single amino acid sequence, without building a multiple sequence alignment (MSA). This guide is for lab and computational biology researchers who need to install it, fold a sequence, and read the confidence output correctly. It covers two routes: the original fair-esm package and the Hugging Face Transformers port.

What ESMFold is used for in research

ESMFold predicts a structure (written as a PDB-format file) for a protein sequence you supply. According to the Hugging Face documentation, it is built from an ESM-2 language-model stem plus a folding head, and it does not run an MSA step at inference. The checkpoints are therefore standalone, need no sequence database, and run much faster than MSA-dependent predictors. The method is described in Lin et al., “Language models of protein sequences at the scale of evolution enable accurate structure prediction” (bioRxiv 2022; published in Science 379:1123-1130, 2023, doi:10.1126/science.ade2574).

Typical uses are quick structural hypotheses for a sequence with no experimental structure, bulk prediction from a FASTA file, and sanity-checking designed or mutated sequences. For proteins that already have a curated entry, look the entry up first in the AlphaFold Protein Structure Database rather than re-predicting it.

Install or access (official source only)

The official repository is facebookresearch/esm on GitHub. It was archived by its owner on 1 August 2024 and is read-only: it still works as released, but it receives no further fixes, so pin your versions.

Route 1: fair-esm (original package)

The README requires Python 3.9 or earlier and PyTorch. Install in this order:

1. pip install "fair-esm[esmfold]"
2. pip install 'dllogger @ git+https://github.com/NVIDIA/dllogger.git'
3. pip install 'openfold @ git+https://github.com/aqlaboratory/openfold.git@4b41059694619831a7db195b7e0988fc4ff3a307'

OpenFold needs nvcc and a CUDA-compatible PyTorch build; if step 3 fails, check those two first. The README also offers a conda alternative: conda env create -f environment.yml, which creates an environment named esmfold.

Route 2: Hugging Face Transformers

The Transformers library includes a port, EsmForProteinFolding, with weights at facebook/esmfold_v1. This route avoids the separate OpenFold build.

Model versions and licence

The README recommends esmfold_v1 as the best model; esmfold_v0 was used for the experiments in Lin et al. 2022; the esmfold_structure_module_only_* models are ablations and are not recommended. The repository code is MIT-licensed, and the ESM Metagenomic Atlas data are CC BY 4.0. The README does not state a separate licence for the weights, so check the model card of the checkpoint you download before redistributing anything.

Step-by-step: fold one sequence

With fair-esm

1. Load the model: import torch, esm, then model = esm.pretrained.esmfold_v1() and model = model.eval().cuda().
2. Optional, for long sequences: model.set_chunk_size(128). A smaller chunk size lowers memory use and runs slower.
3. Predict: with torch.no_grad(): output = model.infer_pdb(sequence).
4. Write the returned string to a file, for example structure.pdb.

For a multimer, separate the chains in the input sequence with a colon (:). For many sequences at once, the esm-fold command-line tool predicts in bulk from a FASTA file; its options include --cpu-offload and --max-tokens-per-batch for managing memory.

With Hugging Face Transformers

1. from transformers import AutoTokenizer, EsmForProteinFolding
2. tokenizer = AutoTokenizer.from_pretrained("facebook/esmfold_v1")
3. model = EsmForProteinFolding.from_pretrained("facebook/esmfold_v1")
4. Tokenize the sequence and call the model. The num_recycles argument defaults to None, which uses the configuration’s max_recycles; the documentation recommends this for maximum accuracy at inference.

Output and how to read it

The key output is per-residue confidence, pLDDT, available two ways depending on the route:

Route	Where pLDDT is
fair-esm	In the written PDB file, pLDDT is stored in the b-factor column. The README example reads the file with biotite and takes the mean of b_factor as the overall confidence (88.3 in its example).
Transformers	The model output has a plddt field with per-residue confidence, alongside positions, aatype, residue_index and distogram_logits.

The Transformers documentation cautions that low pLDDT values may indicate model uncertainty or intrinsic disorder, so a low-confidence region is not by itself evidence that the region is wrong or absent in the real protein. When you open the PDB file in a viewer such as PyMOL, colouring by b-factor shows the confidence along the chain. For sequence-level properties of the same input, ProtParam and InterPro give complementary views (physicochemical parameters and domain annotation).

Troubleshooting

• OpenFold fails to build: confirm nvcc is on the path and that the installed PyTorch build matches your CUDA version, per the README. Use the Hugging Face route if you cannot meet this.
• Python version errors: the README states Python 3.9 or earlier for the fair-esm route.
• Out-of-memory on long sequences or large batches: use model.set_chunk_size(128) (slower, less memory), or for the CLI --cpu-offload and --max-tokens-per-batch.
• Using the wrong checkpoint: load esmfold_v1 unless you are reproducing the 2022 experiments, which used esmfold_v0.

Free alternatives

Option	What it does	Source
AlphaFold Protein Structure Database	Look up existing predicted structures instead of running a model; see the AlphaFold DB guide.	alphafold.ebi.ac.uk
ESM Metagenomic Atlas	Web tool and database of predicted structures released with the ESMFold work (data CC BY 4.0).	esmatlas.com

FAQ

How does ESMFold differ from AlphaFold?

ESMFold predicts from a single sequence using a protein language model and needs no MSA at inference, which is why it needs no sequence database and is faster. Predictors that build an MSA depend on databases of related sequences. For an accuracy comparison, read the Science paper’s own benchmarks rather than a summary.

What licence does ESMFold use?

The repository code is MIT-licensed and the ESM Metagenomic Atlas data are CC BY 4.0, per the repository README (read 2026-11-07).

Is ESMFold on Hugging Face?

Yes. The Transformers library provides EsmForProteinFolding with the facebook/esmfold_v1 checkpoint.

Where is the ESMFold paper?

Lin et al., Science 379:1123-1130 (2023), doi:10.1126/science.ade2574; the earlier preprint is on bioRxiv (2022).

Is the ESMFold GitHub repository still maintained?

No. The facebookresearch/esm repository was archived by its owner on 1 August 2024 and is read-only.

Sources (official documentation)

• ESM repository README, github.com/facebookresearch/esm (read 2026-11-07).
• Hugging Face Transformers, ESM model documentation, huggingface.co/docs/transformers/model_doc/esm (read 2026-11-07).
• Lin Z. et al., Science 379:1123-1130 (2023), doi:10.1126/science.ade2574.