← Tutorials
BEGINNER TUTORIALS

Installing and Configuring ESM3: Step-by-Step

Updated ESM3 installation guide: pip, Biohub API access, local model requirements, troubleshooting and links to the official repository.

In brief: Install the maintained esm package. You no longer need to clone the old Facebook ESM2 repository or use run_pretrained_model.py to start ESM3.

Choose between local inference and the Biohub API

ESM3 is a generative model for protein sequence, structure and function. Local inference offers direct control over a supported open checkpoint but needs substantial memory and compatible packages. The Biohub Platform provides a managed option with credentials and usage limits. Choose the approach based on your task, available compute, budget and data-handling requirements.

Do not confuse ESM3 with ESM2 or ESMFold2. Older commands such as esm2_t6_8M_UR50D refer to a different generation of models.

Create an isolated Python environment

Install a current supported Python release and create a clean environment before installing dependencies. On Windows, activate the virtual environment with the appropriate Scripts path; on Linux/macOS, use:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install esm
python -c "import esm; print(esm.__file__)"

Use the official README to confirm platform-specific PyTorch/CUDA dependencies. A successful Python import confirms installation, not that GPU inference or model downloads will work.

Connect to Biohub

Create a Biohub Platform account and API key. Store secrets in an environment variable or secret manager rather than embedding them in notebooks or public repositories. The following matches the official model quickstart; replace the placeholder with your own token:

import os
from esm.sdk.forge import ESM3ForgeInferenceClient

client = ESM3ForgeInferenceClient(
    model="esm3-open-2024-03",
    url="https://biohub.ai",
    token=os.environ["ESM_API_KEY"],
)

Model IDs and availability can change. If authentication fails, verify your account, token permissions, credits, network policy and the current API reference. This snippet creates a client; it does not yet run a biological inference.

Optional: run a model locally

See the official ESM3 README for the latest Hugging Face weights and model ID. Depending on package version, the model may be loaded using ESM3.from_pretrained(...). You may need Hugging Face authentication and enough GPU memory. Avoid assuming all ESM3 sizes can run on a laptop.

For researchers using shared clusters, pin the package version and document driver/CUDA versions. Never claim a run was reproducible without recording weights and environment details.

Troubleshooting checklist

  • Import fails: confirm you installed esm in the currently active environment.
  • CUDA not available: check nvidia-smi and use the supported PyTorch build for your machine.
  • Out of memory: use smaller models or API inference; reduce sequence length and batch size as appropriate.
  • API failure: check token, model ID, quota and documented endpoint.
  • Unexpected outputs: remember that the ESM3 API works with structured ESMProtein objects, not generic ESM2 command-line scripts.

Primary sources and further reading

Editorial review: October 2026. This guide is educational. Model availability and APIs may change; confirm exact versions in the linked documentation. Generated structures and sequences require independent scientific validation.

Scientific context

Research education only. Outputs from protein AI models are predictions and require independent evaluation. Verify APIs, model availability and licensing with official documentation.

✦ AI RESEARCH ASSISTANT

Questions about this article?

Get a concise explanation grounded in ESM3 Academy articles, with links to the sources. No need to leave this page.

Ask AI about this article ↗