mhctools

mhctools runs MHC binding, presentation, immunogenicity and antigen-processing predictors through a single predict() call and returns the same result objects whichever one you use. Swapping NetMHCpan for MHCflurry is a one-line change, and comparing them gives you a DataFrame. Everything runs locally.

Documentation: https://openvax.github.io/mhctools/

Available predictors

I want to predict…	Kind	Predictors
Binding affinity to an allele	`pMHC_affinity`	`NetMHCpan`, `NetMHC`, `NetMHCIIpan`, `NetMHCcons`, `MHCflurry`, `CapHLA`, `SMM`, `SMMPMBEC`
Surface presentation	`pMHC_presentation`	`NetMHCpan41`/`42`, `NetMHCIIpan`, `MHCflurry`, `CapHLA`, `MixMHCpred` (I), `MixMHC2pred` (II), `BigMHC`
How long the pMHC complex lasts	`pMHC_stability`	`NetMHCstabpan`
Combined antigen processing	`antigen_processing`	`MHCflurry`
Proteasomal cleavage	`proteasome_cleavage`	`Pepsickle`, `NetChop`, `NetCleave_I`
Endolysosomal cleavage (class II)	`endolysosomal_cleavage`	`NetCleave_II`
TAP transport into the ER	`tap_transport`	`DeepTAP`
ERAP1 N-terminal trimming	`erap_trimming`	`ERAMER`
Whether a T cell responds	`immunogenicity`	`Calis`, `PRIME`, `BigMHC_IM`, `DeepImmuno`, `TLimmuno2` (II)
Whether a specific TCR recognises it	`pMHC_TCR_binding`	`NetTCR`, `Tulip`, `MixTCRpred`
How long the free peptide survives	`peptide_half_life`	`PeptiVerse`, `PlifePred2`
Which peptidase cuts which bond	none	cleavage API

Predictor matrix: every predictor, class, command-line name, input, install route and license on one page.
Choosing a predictor and known limits. Several of these models are weaker than their own papers suggest; read the limits before you trust a score.

RandomBindingPredictor is built in and produces random affinities, which is occasionally useful as a null baseline.

Install and predict

pip install mhctools
mhctools fetch mhcflurry     # MHCflurry ships as a dependency; this downloads its weights

from mhctools import MHCflurry

predictor = MHCflurry(alleles=["HLA-A*02:01", "HLA-B*07:02"])
results = predictor.predict(["SIINFEKL", "GILGFVFTL"])

for r in results:
    if r.affinity:
        print(f"{r.peptide} -> {r.affinity.allele} IC50={r.affinity.value:.1f}nM")

predict() returns one PeptideResult per input peptide, in input order. Each exposes an accessor per kind of prediction (r.affinity, r.presentation, r.immunogenicity, ...) that is None when the predictor does not produce that kind. Scan proteins with predict_proteins(), and get a pandas DataFrame from any *_dataframe() method. See results and DataFrames.

Calis needs no download. Most other predictors need model weights or an external tool first (see below). The command line does the same job:

mhctools --sequence SIINFEKL SIINFEKLQ --mhc-predictor mhcflurry --mhc-alleles A0201

Getting models

Most predictors need something downloaded first, with one command for all of it:

mhctools ls                       # what exists, where it lives, who manages it
mhctools fetch mhcflurry          # get it
mhctools predictors               # can it actually run?

fetch is idempotent. Academic-licensed tools need an explicit --accept-license, and the DTU NetMHC family needs a license you request from DTU directly. See getting models and licensing.

Beyond peptide-MHC

Per-bond peptidase evidence, including contextual batches for epitopes with flanks and complete vaccine constructs under tumor, APC and extracellular scenarios.
Route-aware vaccine reports: mhctools vaccine-report writes a sequence-centered PDF with route policies and checksums.
Assay-aware benchmarks: mhctools benchmark evaluates source-linked observations with training-overlap reporting.
Peptide PK, uptake and exposure result kinds.

Documentation

Start here
Command line	Every `mhctools` subcommand
Results and DataFrames	`PeptideResult`, `Prediction`, columns
Recipes	Scan proteins, many genotypes, annotate a table
Allele names	Accepted spellings and errors
Troubleshooting	Common failures
Migration guide	Old names and what replaced them

Development

./develop.sh    # editable install
./lint.sh       # ruff
./test.sh       # pytest

See the testing guide for a complete run with no skipped tests. Releases are described in RELEASING.md.

Metadata

Release files for mhctools 3.46.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mhctools 3.46.3
File	Size	Uploaded
mhctools-3.46.3.tar.gz	541.2 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mhctools 3.46.3
File	Interpreter	ABI	Platform	Reset
mhctools-3.46.3-py3-none-any.whl 314.1 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 855.2 kB

Release files / mhctools-3.46.3.tar.gz

Download URL	mhctools-3.46.3.tar.gz
Size	541.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`933fc2ba302905a67c099cf6ff4238b727c12a74706992cacdc171b478533f1d`
BLAKE2b-256 checksum How to use checksums	`db661080f44b6ab006215b45c8edffe8e2c7c3c0f06583ae6336485c6b432344`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.6`

Release files / mhctools-3.46.3-py3-none-any.whl

Download URL	mhctools-3.46.3-py3-none-any.whl
Size	314.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a6fca5ed5ae3f255030b6fc75d146a132ccda53d9b4f26161fb553a16dc0e828`
BLAKE2b-256 checksum How to use checksums	`ae23ecab959452df232f2e9f3227d4a349779537644f74addce56a737a8062d4`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.6`