Medical 
oncept Annotation Tool (version 2)
MedCAT can be used to extract information from Electronic Health Records (EHRs) and link it to biomedical ontologies like SNOMED-CT, UMLS, or HPO (and potentially other ontologies). Original paper for v1 on arXiv.
Why MedCAT v2?
MedCAT v2 is a comprehensive refactor designed to improve modularity, flexibility, and maintainability. The core library is now lightweight, with optional extras (spaCy tokenization, MetaCAT, DeID, RelCAT) available as separate installable features—allowing you to install only what you need. This modular approach reduces dependencies, enables smaller installs, and provides better separation of concerns. Additionally, v2 reduces internal coupling with spaCy, allowing for alternative tokenizers and greater extensibility. The new architecture makes it easier to create custom components and addons, while improving code maintainability and preparing the foundation for future enhancements. For most users, single-threaded inference APIs remain unchanged, ensuring a smooth transition.
There's a number of breaking changes in MedCAT v2 compared to v1. When moving from v1 to v2, please refer to the migration guide. Details on breaking are outlined here.
Official Docs here
Discussion Forum discourse
Available Models
We have 2 public v2 models available:
- SnomedCT UK Clinical edition 39.0 (Oct 2024) and UK Drug Extension 39.0 (July 2024) based model enriched with UMLS 2024AA; trained only on MIMIC-IV
- SnomedCT UK Clinical edition 40.2 (June 2025) and UK Drug Extension 40.3 (July 2024) based model enriched with UMLS 2024AA; trained only on MIMIC-IV
There are also a number of MedCAT v1 models available that can automatically be converted if required.
To download any of these models, please follow this link and sign in using your NIH / UMLS API key. You will then be redirected to the MedCAT model download form. Please complete this form and you will be provided a download link.
While we encourage you use MedCAT v2 and the models in that native format, if you download an older version MedCAT v2 will be able to load it and covnert it to the format it knows. However, the loading process will be considerably longerin those cases.
If you wish you can also convert the v1 models into the v2 format (see tutorial).
from medcat.utils.legacy import legacy_converter
from medcat.storage.serialisers import AvailableSerialisers
old_model = '<path to old v1 model>'
new_model_dir = '<dir to place new model in>'
legacy_converter.do_conversion(old_model_path, new_model_dir, AvailableSerialisers.dill)
OR
model_path = "models/medcat1_model_pack.zip"
new_model_folder = "models" # file in this folder
! python -m medcat.utils.legacy.legacy_converter $model_path $new_model_folder --verbose
News
- New public 2024 and 2025 Snomed models were uploaded and made available 7. October 2025.
- MedCAT 2.0.0 was released 18. August 2025.
Installation
MedCAT v2 has its first full release
pip install medcat
Do note that this installs only the core MedCAT v2.
It does not necessary dependencies for spacy-based tokenizing or MetaCATs or DeID.
However, all of those are supported as well.
You can install them as follows:
pip install "medcat[spacy]" # for spacy-based tokenizer
pip install "medcat[meta-cat]" # for MetaCAT
pip install "medcat[deid]" # for DeID models
pip install "medcat[spacy,meta-cat,deid,rel-cat,dict-ner]" # for all of the above
Installing plugins
MedCAT v2 supports external plugins that can provide new components (e.g. alternative NER models, addons, tokenizers) via Python entry points.
- Curated plugins: The
medcat.plugins.catalogmodule ships with a curated plugin catalog that can be updated from a remote JSON file. - Installer: The
medcat.plugins.installer.PluginInstallationManagerwraps apip-based installer and knows how to resolve a compatible plugin version for your current MedCAT version. - CLI: You can install curated plugins directly from the command line:
python -m medcat plugins install medcat-gliner
This will:
- look up
medcat-glinerin the curated catalog, - resolve a version compatible with your installed MedCAT,
- and install it using
pip.
You can also:
-
pass
--dry-runto show what would be installed without making changes:python -m medcat plugins install --dry-run medcat-gliner
-
override the version/ref explicitly (e.g. when testing a branch or tag):
python -m medcat plugins install medcat-gliner --force-version main
If a plugin requires authentication (for example, private Git repositories), MedCAT will log a warning and the installer will surface pip’s error messages if credentials are missing or incorrect.
Version / update checking
MedCAT now has the ability to check for newer versions of itself on PyPI (or a local mirror of it). This is so users don't get left behind too far with older versions of our software. This is configurable by evnironmental variables so that sys admins (e.g for JupyterHub) can specify the settings they wish. Version checks are done once a week and the results are cached.
Below is a table of the environmental variables that govern the version checking and their defaults.
| Variable | Default | Description |
|---|---|---|
MEDCAT_DISABLE_VERSION_CHECK |
(unset) | When set to true, yes or disable, disables the version update check entirely. Useful for CI environments, offline setups, or deployments where external network access is restricted. |
MEDCAT_PYPI_URL |
https://pypi.org/pypi |
Base URL used to query package metadata. Can be changed to a PyPI mirror or internal repository that exposes the /pypi/{pkg}/json API. |
MEDCAT_MINOR_UPDATE_THRESHOLD |
3 |
Number of newer minor versions (e.g. 1.4.x, 1.5.x) that must exist before MedCAT emits a “newer version available” log message. |
MEDCAT_PATCH_UPDATE_THRESHOLD |
3 |
Number of newer patch versions (e.g. 1.3.1, 1.3.2, 1.3.3) on the same minor line required before emitting an informational update message. |
MEDCAT_VERSION_UPDATE_LOG_LEVEL |
INFO |
Logging level used when reporting available newer versions (minor/patch thresholds). Accepts any valid logging level string (DEBUG, INFO, WARNING, ERROR, CRITICAL). |
MEDCAT_VERSION_UPDATE_YANKED_LOG_LEVEL |
WARNING |
Logging level used when reporting that the current version has been yanked on PyPI. Accepts the same values as above. |
Demo
The MedCAT v2 demo web app is available here.
Key Concepts
- Components: The building blocks of MedCAT (NER, Entity Linking, preprocessing, etc.)
- Addons: Components that extend the core NER+EL pipeline with additional processing stages
- Plugins: External packages that provide new component implementations or other functionality via entry points
See Architecture Documentation for detailed information.
Tutorials
A guide on how to use MedCAT v2 is available at on the medcat documentation page on docs.cogstack.org
Acknowledgements
Entity extraction was trained on MedMentions In total it has ~ 35K entites from UMLS
The vocabulary was compiled from Wiktionary In total ~ 800K unique words
Powered By
A big thank you goes to spaCy and Hugging Face - who made life a million times easier.
Citation
MedCAT v2 citation:
@inproceedings{ratas-etal-2026-medcat,
title = "{M}ed{CAT} v2: a modular, extensible architecture for clinical named entity recognition and linking under real-world privacy and compute constraints",
author = "Ratas, Mart and
Searle, Thomas and
Sutton, Adam and
Dobson, Richard",
editor = "Demner-Fushman, Dina and
Ananiadou, Sophia and
Roberts, Kirk and
Tsujii, Junichi",
booktitle = "{B}io{NLP} 2026",
month = jul,
year = "2026",
address = "San Diego, California",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2026.bionlp-1.17/",
doi = "10.18653/v1/2026.bionlp-1.17",
pages = "191--198",
ISBN = "979-8-89176-434-7",
abstract = "MedCAT is an open-source framework for clinical named entity recognition and linking (NER+L) widely used in research and healthcare settings. We present MedCAT v2, a re-engineered version designed to improve modularity, extensibility, and maintainability while preserving the core functionality and performance of previous releases. The new architecture introduces a registry-based component system and a flexible pipeline that enables easy substitution of components, integration of alternative methods, and future expansion, including support for pre-trained components across the full NER+L and contextualisation workflow. This enables systematic exploration of clinical NER+L design trade-offs by evaluating different components in the pipeline. Evaluation across multiple public datasets shows equivalent or improved performance compared to earlier versions, with reduced integration overhead and improved runtime flexibility. The framework also supports optional extensions such as meta-annotation, relation extraction, providing a unified and reproducible environment for clinical NLP in real-world settings."
}
MedCAT v1 citation
@ARTICLE{Kraljevic2021-ln,
title="Multi-domain clinical natural language processing with {MedCAT}: The Medical Concept Annotation Toolkit",
author="Kraljevic, Zeljko and Searle, Thomas and Shek, Anthony and Roguski, Lukasz and Noor, Kawsar and Bean, Daniel and Mascio, Aurelie and Zhu, Leilei and Folarin, Amos A and Roberts, Angus and Bendayan, Rebecca and Richardson, Mark P and Stewart, Robert and Shah, Anoop D and Wong, Wai Keong and Ibrahim, Zina and Teo, James T and Dobson, Richard J B",
journal="Artif. Intell. Med.",
volume=117,
pages="102083",
month=jul,
year=2021,
issn="0933-3657",
doi="10.1016/j.artmed.2021.102083"
}
</details>
3 maintainers
Release files for medcat 2.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| medcat-2.9.0.tar.gz | 966.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| medcat-2.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / medcat-2.9.0.tar.gz
| Download URL | medcat-2.9.0.tar.gz |
|---|---|
| Size | 966.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eb154f10479c3a31c7641283811a1616b446985fff91858ad2b890804a54519f
|
|
BLAKE2b-256 checksum How to use checksums |
4d16cf0265cb197dc242b83e2bf8e18d466aaf9c100e3a5a48983f5846d83be2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.
Transparency logRelease files / medcat-2.9.0-py3-none-any.whl
| Download URL | medcat-2.9.0-py3-none-any.whl |
|---|---|
| Size | 320.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6f0f1c2f9c275ab08bfe9a4098fb84afd0881a999db72aa8ddc61bdb6dcf61eb
|
|
BLAKE2b-256 checksum How to use checksums |
22b6b01eb50ea3f040b4dac7356bfa49e9968be0647b4f3539eeb53a64d35426
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.
Transparency log
