Install ESM-2 Protein Language Model (fair-esm 2.0.0)

Most teams install the 15B ESM-2 first and then spend a week fighting OOM. That’s backwards. The protein language model that actually ships in production labs is usually the 650M (or smaller) checkpoint – you get most of the structure signal without needing an A100-80GB fleet.

This is a straight deployment guide for ESM-2 via the official fair-esm package (latest PyPI release 2.0.0, dated 2022-11-01). Meta’s FAIR repo went read-only on 1 Aug 2024, but the wheels and weight URLs still resolve. System requirements, copy-paste install, verification, the errors people actually hit, cleanup – no recycled README embedding demo.

System requirements for ESM-2

PyTorch first. CUDA if you’re above toy size. Disk is the quiet killer: weights land in the Torch hub cache on first load, not next to your script.

VRAM figures above are approximate community/HF-card reports (as of 2024-2025 discussions) – not a Meta SLA. Sequence length and dtype swing them hard.

Funny how often a lab buys the 80GB card before anyone times 650M on the job they actually run. Half the “we need 15B” threads die once embeddings from t33 land in the downstream classifier.

Practical floor: Linux or WSL2, Python 3.8-3.11, a CUDA-matched PyTorch, 16+ GB system RAM. Free disk ≥ the largest weight you’ll pull – esm2_t48_15B_UR50D alone is ~30 GB under ~/.cache/torch/hub/checkpoints. ESMFold extras? That’s Python ≤3.9 plus nvcc. Skip unless you need PDBs from this stack.

Official download source

Package beats a random fork.

• PyPI: fair-esm 2.0.0
• Source (archived): github.com/facebookresearch/esm
• Weights: auto-fetched from https://dl.fbaipublicfiles.com/fair-esm/models/ into the Torch hub cache
• Paper: Lin et al., Science 2023 (doi:10.1126/science.ade2574)

Already living in Hugging Face Transformers? Load facebook/esm2_* checkpoints with AutoModel.from_pretrained – same weights, different entry point (HF ESM docs).

Install ESM-2 step by step (fair-esm 2.0.0)

Clean env. Biohub’s newer esm package (ESMC / ESMFold2) also owns import esm. One env, two packages – you’ll lose an afternoon.

# 1. Env
conda create -n esm2 python=3.10 -y
conda activate esm2

# 2. PyTorch first (CUDA wheel from pytorch.org that matches your driver)
pip install torch torchvision torchaudio

# 3. Pin the known-good PyPI release
pip install fair-esm==2.0.0

# Optional: install from archived main (still resolves as of late 2025)
# pip install git+https://github.com/facebookresearch/esm.git

Embeddings-only and you already have Transformers:

pip install transformers
# AutoModel.from_pretrained("facebook/esm2_t33_650M_UR50D")

No separate binary download. First esm.pretrained.esm2_... call pulls weights.

First-time configuration

Almost no config file. Minimum viable run:

import torch
import esm

model, alphabet = esm.pretrained.esm2_t33_650M_UR50D()
batch_converter = alphabet.get_batch_converter()
model.eval()
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)

Pro tip: Set TORCH_HOME or free space under ~/.cache/torch before the first 3B/15B load. A full checkpoint set eats tens of GB with zero prompt.

15B on one GPU? Official README path is Fairscale FSDP + CPU offload – not plain .cuda(). Don’t start day one there.

Verify the install works

Smoke test. Tensor shape print; seconds on GPU at 8M.

import torch, esm
print("fair-esm import OK")
model, alphabet = esm.pretrained.esm2_t6_8M_UR50D() # tiny for speed
batch_converter = alphabet.get_batch_converter()
model.eval()
data = [("test", "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGDG")]
labels, strs, tokens = batch_converter(data)
with torch.no_grad():
 out = model(tokens, repr_layers=[6], return_contacts=False)
print(out["representations"][6].shape) # expect [1, L, 320]
print("ESM-2 forward pass OK")

Also: python -c "import esm; print(esm.__file__)" – must sit inside this env. Leftover site-packages from another esm name will lie to you.

Common install errors and fixes

ModuleNotFoundError: No module named ‘esm.model.esm1’; ‘esm.model’ is not a package
Broken early 1.0.x wheels (GitHub issues #257 / #253). Maintainer fix: pip uninstall fair-esm -y && pip install fair-esm==2.0.0 (or ≥1.0.2). Still broken? Old esm directory on PYTHONPATH.

AttributeError: module ‘esm.pretrained’ has no attribute ‘esm2_t6_8M_UR50D’
Wrong package or ancient install. Wipe anything named esm/fair-esm, reinstall 2.0.0, restart the kernel.

CUDA OOM on 3B/15B
Drop to 650M, shorten sequences, half precision, or the FSDP + CPU offload example above. Batch size 1 is mandatory at 15B.

import esm resolves Biohub ESMC, not fair-esm
Separate conda envs. Some community wheels rename fair-esm to esm2 – better than two top-level esm packages in one site-packages.

openfold / nvcc failures
Only if you installed fair-esm[esmfold]. Check nvcc --version and CUDA-matched PyTorch. Pure LM embeddings don’t need that extra.

Upgrade and uninstall

PyPI stops at 2.0.0 – project frozen with the archive. Refresh from git if you must:

pip uninstall fair-esm -y
pip install git+https://github.com/facebookresearch/esm.git

Full cleanup:

pip uninstall fair-esm -y
rm -rf ~/.cache/torch/hub/checkpoints/esm2_*
conda env remove -n esm2

2026-era ESMC / ESMFold2 is pip install esm (Biohub) – different tutorial, different env.

Next: run the 8M smoke test, swap the loader to esm2_t33_650M_UR50D, point it at one FASTA. Clean forward pass = you’re deployed.

FAQ

Which ESM-2 size should I install first?

Take esm2_t33_650M_UR50D if the box has ≥8 GB VRAM. That’s the size most pipelines treat as the practical default – enough signal for embeddings and variant work without multi-GPU choreography. Example: a single 4090 clears t33 batches all day; jump to 3B only after you’ve measured a real gap on your sequences, with FSDP ready if you continue to 15B.

Does fair-esm 2.0.0 still work after the GitHub archive?

Yes. Turns out the PyPI wheels and dl.fbaipublicfiles.com weight URLs still serve fine after the 1 Aug 2024 read-only switch. Archive means no new patches on that codebase – period. Teams that want a second copy of the same checkpoints often pin Hugging Face facebook/esm2_* so one host outage doesn’t freeze inference. Classic ESM-2 (as of 2025-2026) still sits beside newer Biohub models in a lot of production stacks; just don’t expect FAIR-side bugfixes.

Can I run ESM-2 on CPU only?

8M and 35M: fine. 150M: light batches only. 650M crawls; 3B/15B aren’t realistic for real workloads on CPU. Rent a GPU once, cache embeddings, stop looping full forwards on a laptop.