Install NVIDIA BioNeMo v2.6.3: Biopharma AI Framework Guide

End state: a working NVIDIA BioNeMo container running on your GPU box, with an authenticated NGC session, model weights cached to a mounted volume, and a shell prompt inside bionemo-framework:2.6.3 ready to run ESM-2, Geneformer, or Evo2. This biopharma AI framework tutorial walks that path in reverse – from verification back through the install steps most guides skip.

Two things before you start. First, BioNeMo Framework and BioNeMo NIMs are different products – the Framework is for training and fine-tuning; NIMs are inference microservices. Only want to hit an API endpoint? Stop here and grab a NIM. Second, the latest tag referenced in active GitHub issues as of late 2025 is v2.6.3 – this may have changed, so cross-check the releases page before pulling.

System requirements (the honest version)

The docs list a GPU. What they don’t spell out is how narrow the supported hardware window actually is.

Per the official hardware prerequisites: bfloat16 requires Compute Capability ≥8.0, and running on older GPUs is not supported. Translation: your V100 will technically boot the container and then blow up somewhere unhelpful. Don’t waste the afternoon.

Get your NGC credentials first

Skip this and every subsequent step fails silently. The BioNeMo container lives on the NGC Container Registry – you need a free NGC account, then generate an API Key at User > Setup > Generate API Key.

docker login nvcr.io
# Username: $oauthtoken
# Password: <paste your NGC API key here>

Turns out the username is literally the string $oauthtoken, not your email. This trips up half of first-time users.

Pull and run BioNeMo v2.6.3

Docker is the recommended path. Source builds exist – but read the errors section before going down that road.

export BIONEMO_TAG=2.6.3
docker pull nvcr.io/nvidia/clara/bionemo-framework:${BIONEMO_TAG}

# Set up local cache dirs (persists across container runs)
mkdir -p ~/bionemo/{data,models,results}
export LOCAL_DATA_PATH=~/bionemo/data
export LOCAL_MODELS_PATH=~/bionemo/models
export LOCAL_RESULTS_PATH=~/bionemo/results

# Launch the container
docker run 
 --rm -it 
 --gpus all 
 --network host 
 --shm-size=4g 
 -e NGC_CLI_API_KEY 
 -e WANDB_API_KEY 
 -v $LOCAL_DATA_PATH:/workspace/bionemo/data 
 -v $LOCAL_MODELS_PATH:/workspace/bionemo/models 
 -v $LOCAL_RESULTS_PATH:/workspace/bionemo/results 
 nvcr.io/nvidia/clara/bionemo-framework:${BIONEMO_TAG} 
 /bin/bash

Why --shm-size=4g? Shared memory in the container gets set to 4 GB – PyTorch DataLoaders and Megatron’s memory-heavy operations need it. Skip it and you’ll get cryptic worker crashes during data loading. The official initialization guide lists all recommended flags.

Everything you need for running ESM-2, Geneformer, or Evo2 comes pre-built in the image. No separate installs.

Verify the install actually works

Inside the container, don’t just run python -c "import bionemo". That tells you nothing about whether your GPUs are visible to the framework. Do this instead:

# 1. Check GPU visibility from inside the container
nvidia-smi

# 2. Confirm PyTorch sees the GPUs and CUDA works
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count(), torch.cuda.get_device_name(0))"

# 3. Import BioNeMo sub-packages
python -c "from bionemo.esm2 import model; print('esm2 OK')"
python -c "from bionemo.core.data.load import load; print('core OK')"

# 4. Run a small sanity test (uses cached weights if present)
download_bionemo_data esm2/650m:2.0 --source ngc

If step 2 prints False, your host is missing the NVIDIA Container Toolkit – not a BioNeMo problem. If step 3 fails on an ImportError for nemo.collections.llm.gpt.model.hyena, you accidentally installed from source into a conda env. Community reports suggest upgrading the nemo_toolkit resolves this in some setups, but the version that works varies – just use the container.

The v2.6.3 bug nobody mentions on the download page

If your workflow depends on Evo2 inference, read this before pulling the tag.

Heads up: On v2.6.3, infer_evo2 is broken – a FlashAttention KV cache signature mismatch throws RuntimeError: If key is supplied, seqlens_k must also be passed in (reported in GitHub issue #1015). The predict_evo2 command still works fine. Until a patch ships, use predict_evo2 for generation or pin the previous tag.

Common install errors and their real fixes

• No file descriptors available (os error 24) during docker build. Add --ulimit nofile=65535:65535 to your docker build command – it’s documented in the official README. The multi-stage build opens a large number of files during the TransformerEngine compile step, which hits default OS limits.
• Repo root is not pip-installable. Running pip install . at the repo root fails with Multiple top-level packages discovered in a flat-layout: ['LICENSE', 'internal', 'docker_build_patches']. This is a setuptools flat-layout discovery issue (GitHub issue #953). The fix: install individual sub-packages/ directories, or use the container.
• Multi-GPU training hangs on AWS EC2. The Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 22.04) ships driver/toolkit versions that conflict with NCCL under BioNeMo’s parallelism setup. Switch to the NVIDIA GPU-Optimized AMI instead – AMI ID ami-075a0f15f2d44a65e at time of writing (GitHub issue #644; verify the current ID in the AWS Marketplace before launching, as AMI IDs are region-specific and may rotate).
• NGC downloads fail silently inside the container. Regenerate your API key. Old keys tied to expired sessions look valid but return 401 on binary blob endpoints – a pattern reported across multiple open GitHub issues.

Is the framework actually faster? A quick reality check

According to the BioNeMo Framework paper (arXiv:2411.10548), on identical hardware the framework hit 59.2% model flops utilization compared to 40.1% for an Accelerate baseline, with roughly 1.47x higher training throughput for ESM-2.

Whether that speedup matters depends on your batch. On an H100 fine-tuning a 650M ESM-2, you’ll notice it. On a single A10 running MolMIM at batch 8, the parallelism overhead eats most of the win.

Upgrading and uninstalling

Upgrades are trivial with Docker – pull the next tag. State lives in your mounted volumes, not the container, so there’s no in-place migration to worry about.

# Upgrade
docker pull nvcr.io/nvidia/clara/bionemo-framework:2.7 # or whatever ships next

# Uninstall / cleanup
docker rmi nvcr.io/nvidia/clara/bionemo-framework:2.6.3
docker image prune -a # removes dangling layers (frees ~30 GB)
rm -rf ~/bionemo # only if you don't need cached models

One checkpoint note: weights saved under 2.x should load in 2.6.3 without conversion. ESM-2 LoRA adapters trained against earlier versions may behave differently – if you see unexpected inference results after upgrading, re-training the adapter is the safe call. Also: notebook-based training isn’t supported at all due to Megatron restrictions (per the official FAQ). Jupyter users have to shell out via the Python subprocess module or bash cell magic. If your team lives in notebooks, plan for this before migrating a workflow.

FAQ

Do I need NVIDIA AI Enterprise to use BioNeMo?

No. BioNeMo Framework is free under Apache 2.0 (per the official FAQ). Enterprise support is optional – most academic and startup users never touch it.

Can I run BioNeMo on an ARM machine like a GH200?

Yes, but you need the right image. A Dockerfile.arm exists for GH200 machines, and NVIDIA publishes a multi-architecture container to NGC – pull the same nvcr.io/nvidia/clara/bionemo-framework:2.6.3 tag and Docker resolves the right architecture automatically. Practically speaking: if you’re on a Grace CPU with Hopper GPU, this is the recommended setup and training throughput on Evo2-class models scales well with the unified memory. If you’re on a plain aarch64 board without a supported GPU, none of this applies – the framework won’t do anything useful without a Compute Capability ≥8.0 GPU attached.

What’s the difference between BioNeMo Framework and BioNeMo Recipes?

Recipes are reference implementations – self-contained Docker environments showing specific training patterns that you copy and modify. The Framework is the full sub-package library you import in code. Different tools for different stages of a project.

What to do next

Container running, nvidia-smi clean? Grab the ESM-2 650M checkpoint with download_bionemo_data esm2/650m:2.0 --source ngc, then run the fine-tuning example from sub-packages/bionemo-esm2/examples/ against your own protein FASTA. That’s the shortest path from install to a real fine-tune.