Skip to content

Installing optional backends

Most predictors need something downloaded or installed first. There are two routes:

  • mhctools fetch <name> installs what mhctools can legally and safely fetch. This is the route for most users; see getting models.
  • The repository's scripts/setup_test_backends.py provisions the heavier backends (isolated Python runtimes, pinned snapshots) from a source checkout. It is the route CI uses and what you want if you are running the full test suite. If you installed from PyPI, use fetch and the environment variables instead.

Check what is installed and whether it runs with mhctools ls and mhctools predictors. This page covers the backends that need more than a single fetch.

Source-checkout setup

Install mhctools in editable mode with its development dependencies. The setup below covers CapHLA, TULIP, MixTCRpred, PeptiVerse, PlifePred2/Pfeature, MixMHCpred 3, MixMHC2pred, PRIME, DeepImmuno, TLimmuno2, NetCleave, and NetTCR. It supplements the other predictors listed in the predictor reference; mhctools ls reports their availability. This is several GB of downloads, including ESM2's 2.6 GB weights.

Prerequisites:

  • Python 3.11, git, Perl, and MAFFT, on macOS or Linux x86-64.
  • Rosetta on Apple Silicon, for the official macOS MixMHC2pred binary.
  • g++ on Linux, to build PRIME's supplied C++ source.
  • The caphla and nettcr extras, because CapHLA and NetTCR run in the main interpreter. Neither extra requires TensorFlow; the keras group below keeps TensorFlow in a separate environment for the predictors that use it.

On Linux you can install a CPU-only torch wheel first from https://download.pytorch.org/whl/cpu.

python -m pip install -e '.[dev,caphla,nettcr]'
python scripts/setup_test_backends.py half-life recognition gfeller keras nettcr smm deeptap --accept-license

The recognition, Gfeller, keras, NetTCR and SMM groups fetch separately licensed code and weights, so they require --accept-license. Review the terms before using that option, because they are not all the same kind of term:

  • academic / non-commercial: MixTCRpred, MixMHCpred, MixMHC2pred, PRIME;
  • NetTCR academic software license for the nettcr group;
  • Non-Profit Open Software License 3.0: the IEDB MHC-I bundle used by smm (see SMM setup);
  • no published license: TLimmuno2 and NetCleave, which is why the keras group is gated. Here --accept-license records that you have confirmed your own use is authorized; it cannot accept terms upstream never stated, and it grants no rights mhctools does not have.

DeepImmuno, also in the keras group, is MIT and needs no acceptance of its own. Upstream sources and models are never bundled in mhctools distributions.

The script pins model/source revisions, installs the complete MixMHC2pred official release (including PWM assets), and installs incompatible Python runtimes separately under ignored env/test-backends/. Existing environments are reused. The half-life group also provisions PeptiVerse CPP with its required scikit-learn 1.7.2. The wrappers verify their pinned model hashes before inference. Re-run individual groups to repair or update the local setup.

The script writes env/test-backends/activate.sh, which exports the variables the wrappers read (see environment variables); source it in your shell. An alternate setup root is supported with --root PATH. For how the test suite uses it, see testing.

Local SMM and SMM-PMBEC

The smm setup group installs a 2.4 MB subset of the official IEDB MHC-I 3.1.7 bundle, verifies its pinned SHA-256, and installs its Python code, allele metadata, and model/percentile data. It does not install or execute the bundled DTU binaries. SMM 1.0 and SMM-PMBEC 1.0 run with the current Python interpreter, including on Apple Silicon; no extra Python dependencies are needed. Review LIAI_license.txt (Non-Profit Open Software License 3.0) before accepting the license. Upstream code and models stay outside the package. Setup requires curl; cold downloads use bounded transient-error retries and are promoted from a temporary file only after checksum verification. Model inference needs no network access.

Install it with:

python scripts/setup_test_backends.py smm --accept-license
source env/test-backends/activate.sh
mhctools ls smm

For an existing configured standalone installation, set IEDB_MHCI_EXECUTABLE to an executable launcher that runs python /absolute/path/mhc_i/src/predict_binding.py "$@". Alternatively put that launcher on PATH as iedb-mhci, or pass it with SMM(program_name=...) / --mhc-predictor-path. The official CLI runs locally; errors and incomplete output fail explicitly. mhctools ls smm locates the launcher.

MixMHCpred and PRIME

The gfeller setup group installs the official pinned predictors and a separate Python environment, then configures MIXMHCPRED_PYTHON. It uses the supported API runtime selection, with no test-only launcher. The host can keep pandas 3; the backend needs numpy, pandas below 3, scipy, logomaker and matplotlib. See manual setup and runtime diagnostics. MAFFT remains on the inherited PATH for sequence alignment. PRIME's nested MixMHCpred call uses the same selected interpreter.

DeepTAP and MixTCRpred (torch sidecars)

Both run out-of-process under an interpreter that defaults to the one running mhctools, which need not have their dependencies. MIXTCRPRED_PYTHON is provisioned by the recognition group above. Its sidecar additionally runs with PYTHONNOUSERSITE=1, so packages installed with pip install --user are not visible to it, so install into the interpreter itself.

DeepTAP has a dedicated setup group with an isolated runtime and the pinned Apache-2.0 model snapshot:

python scripts/setup_test_backends.py deeptap
source env/test-backends/activate.sh
python -m pytest tests/test_deeptap.py --require-all -ra

It needs no license-acceptance flag. The setup pins PyTorch 2.14.0, Lightning 2.6.6, NumPy 2.4.6 and pandas 3.0.6, using CPU PyTorch wheels on Linux, and checks the runtime's dependencies with pip check. Both classification and regression inference are required in CI. You can also supply DEEPTAP_HOME and DEEPTAP_PYTHON yourself; the current interpreter is used when the latter is unset.

Variable Needs
DEEPTAP_PYTHON torch, pytorch_lightning, numpy, pandas
MIXTCRPRED_PYTHON torch, torchvision, pytorch_lightning, numpy, pandas, scipy, sklearn

A *_PYTHON path that does not exist raises instead of skipping: that is a misconfiguration to fix, not a backend to step over.

NetTCR with LiteRT

NetTCR's bundled inference models run under LiteRT without TensorFlow:

python -m pip install -e '.[dev,nettcr]'
python scripts/setup_test_backends.py nettcr --accept-license
source env/test-backends/activate.sh

The setup group fetches the pinned pan-model weights and sets NETTCR_DIR. The existing nettcr extra supplies ai-edge-litert in the host interpreter. The adapter prefers it over its compatibility TensorFlow Lite fallback, whose deprecated interpreter emitted the warning in #479. Installing TensorFlow to run another predictor is not needed to enable NetTCR.

DeepImmuno, TLimmuno2, and NetCleave (isolated TensorFlow)

DeepImmuno and TLimmuno2 ship weights from the Keras 2 era. Modern TensorFlow reaches that API through the tf-keras shim with TF_USE_LEGACY_KERAS=1, which the wrappers set for their subprocess. NetCleave uses modern Keras in the same isolated runtime, without that per-process setting:

python scripts/setup_test_backends.py keras --accept-license
source env/test-backends/activate.sh

The group pins tensorflow==2.17.0 with the matching tf-keras==2.17.0 and sets DEEPIMMUNO_PYTHON, TLIMMUNO2_PYTHON, and NETCLEAVE_PYTHON to it. It also installs NetCleave's scikit-learn, Biopython, and matplotlib dependencies. Pinning the pair matters: a mismatched pair imports tensorflow successfully and then raises AttributeError on tensorflow.keras.

An explicit NetCleave python_executable argument overrides NETCLEAVE_PYTHON; without either it uses the current interpreter. The same precedence applies to the other two wrappers with their respective environment variables.

Pepsickle gradient-boosted digestion models

The upstream artifact was trained with scikit-learn 0.23.2 and cannot be loaded by current scikit-learn. Provision its pinned Python 3.8.20/Linux x86-64 runtime with Docker (emulation is used on Apple Silicon):

python scripts/setup_test_backends.py pepsickle
source env/test-backends/activate.sh

The generated launcher binds to the built image ID, disables networking, and does not mount host files. CI runs both constitutive and immunoproteasome profiles against direct upstream inference and checks runtime provenance. Host neural Pepsickle dependencies are unchanged. This is implementation conformance, not held-out biological validation; see cleavage validation.

Legacy NetMHC on Apple Silicon

NetMHC 3.4 and NetMHCcons need Python 2 and Linux x86 executables. With Docker running and an existing licensed netmhc-bundle installation:

export NETMHC_BUNDLE_HOME=/absolute/path/to/netmhc-bundle
python scripts/setup_test_backends.py legacy
source env/test-backends/activate.sh

This builds a pinned Linux runtime and generates test launchers. Each execution mounts the licensed bundle and input files read-only, disables networking, and keeps scratch files in a disposable tmpfs. No licensed tool is copied into the image. Native Linux installations with Python 2 can continue using their existing launchers.

./test.sh loads the generated activation file automatically. Source it before direct pytest or predictor commands so the container launchers take precedence over the native bundle scripts on PATH.