mhcseqs is one executable with three subcommands: build downloads the
sources and writes the CSVs, lookup reads one allele back out of them, and
data manages the cache and the versioned datasets. Run
mhcseqs <command> --help for every option.
| Command | Does |
|---|---|
mhcseqs build |
Download sources and build CSVs |
mhcseqs lookup |
Look up an allele from built CSVs |
mhcseqs data list |
List cached source and built data files |
mhcseqs data install |
Install an immutable versioned dataset |
mhcseqs data path |
Print the path to an installed versioned dataset |
mhcseqs data refresh |
Re-download source FASTA(s) |
mhcseqs data clear |
Delete cached source FASTA(s) |
# Build all output CSVs (writes to ~/.cache/mhcseqs/; set MHCSEQS_DATA to use another
# data directory for downloads, built CSVs and versioned datasets)
mhcseqs build
# Build to a specific directory instead
mhcseqs build --output-dir output/
# Re-download source FASTAs (IMGT/HLA and IPD-MHC publish from a rolling "Latest")
mhcseqs build --force-download
--data-dir sets where the downloaded FASTA files live, separately from
--output-dir for the built CSVs.
mhcseqs lookup "HLA-A*02:01"
--- mhc-full-seqs.csv ---
two_field_allele: HomoSapiens-A*02:01
representative_allele: HomoSapiens-A*02:01:01:100
protein_seq_selection: nested_longest
gene: A
mhc_class: I
chain: alpha
species: Homo sapiens
species_category: human
species_prefix: HomoSapiens
source: imgt
source_id: HLA24674
seq_len: 365
sequence: MAVMAPRTLVLLLSGALALTQTWAGSHSMRYFFTSVSRPGRGEPRFIAVG... (365 aa)
mature_start: 24
mature_sequence: GSHSMRYFFTSVSRPGRGEPRFIAVGYVDDTQFVRFDSDAASQRMEPRAP... (341 aa)
groove1: GSHSMRYFFTSVSRPGRGEPRFIAVGYVDDTQFVRFDSDAASQRMEPRAPWIEQEGPEYWDGETRKVKAHSQTHRVDLGTLRGYYNQSEA
groove2: GSHTVQRMYGCDVGSDWRFLRGYHQYAYDGKDYIALKEDLRSWTAADMAAQTTKHKWEAAHVAEQLRAYLEGTCVEWLRRYLENGKETLQRTD
groove1_len: 90
groove2_len: 93
ig_domain: APKTHMTHHAVSDHEATLRCWALSFYPAEITLTWQRDGEDQTQDTELVETRPAGDGTFQKWAAVVVPSGQEQRYTCHVQHEGLPKPLTLRWEPSS
ig_domain_len: 95
tail: QPTIPIVGIIAGLVLFGAVITGAVVAAVMWRRKSSDRKGGSYSQAASSDSAQGSDVSLTACKV
tail_len: 63
domain_architecture: signal_peptide>g_alpha1>g_alpha2>c1_alpha3>tail_linker>transmembrane>cytoplasmic_tail
domain_spans: signal_peptide:1-24;g_alpha1:25-114;g_alpha2:115-207;c1_alpha3:208-302;tail_linker:303-307;transmembrane:308-331;cytoplasmic_tail:332-365
groove_status: ok
groove_flags:
anchor_type: alpha2_cys
is_null: False
is_questionable: False
is_pseudogene: False
is_functional: True
--- mhc-seqs-raw.csv ---
allele_raw: A*02:01:01:01
allele_normalized: HomoSapiens-A*02:01:01:01
two_field_allele: HomoSapiens-A*02:01
gene: A
mhc_class: I
chain: alpha
species: Homo sapiens
species_category: human
species_prefix: HomoSapiens
source: imgt
source_id: HLA00005
seq_len: 365
sequence: MAVMAPRTLVLLLSGALALTQTWAGSHSMRYFFTSVSRPGRGEPRFIAVG... (365 aa)
has_signal_peptide: True
signal_peptide_len: 24
signal_peptide_seq: MAVMAPRTLVLLLSGALALTQTWA
is_null: False
is_questionable: False
is_pseudogene: False
The first block is the representative row from mhc-full-seqs.csv; the
second is the first matching source row from mhc-seqs-raw.csv. The
groove_seq line is omitted above for width; the command prints it
between groove2 and groove1_len. Non-human alleles work the same way:
mhcseqs lookup "Mamu-A1*001:01". Use --output-dir when the CSVs are not in
~/.cache/mhcseqs.
mhcseqs data list
mhcseqs data list --details # full paths and source URLs
Data directory: /Users/you/.cache/mhcseqs
Source FASTA files
FILE SIZE UPDATED STATUS
hla_prot.fasta 14.0 MB 61d ago present
ipd_mhc_prot.fasta 3.6 MB 61d ago present
Built CSVs and reports
FILE SIZE UPDATED STATUS
mhc-seqs-raw.csv 30.6 MB 61d ago present
mhc-full-seqs.csv 58.6 MB 61d ago present
mhc-merge-report.txt 16.4 KB 61d ago present
mhc-validation-report.txt 72.8 KB 61d ago present
Versioned datasets
DATASET VERSION STATUS
mhc-proteins uniprot-2026_03-r1 not installed
mhc-proteins uniprot-2026_03-r2 not installed
Use 'mhcseqs data list --details' for full paths and source URLs.
# Re-download source FASTAs without rebuilding
mhcseqs data refresh
# Delete cached files
mhcseqs data clear # source FASTAs
mhcseqs data clear --built # also remove built CSVs/reports
mhcseqs data clear --built-only # only built CSVs/reports
mhcseqs data clear --source imgt_hla # just one source
mhcseqs data install mhc-proteins
mhcseqs data path mhc-proteins
mhcseqs data install mhc-proteins --version uniprot-2026_03-r2
Code releases and data releases are deliberately independent, so pin a data
version in automated work. See datasets and columns for what
mhc-proteins contains.
mhcseqs --version