CMS ICD

cms-icd provides version-aware, structured access to official CMS ICD-10-CM and ICD-10-PCS materials. Downloads and parsing are lazy: using diagnosis codes does not download PCS files, and reading a tabular list does not parse indexes or guideline PDFs.

Python 3.12 or newer is required. The package is tested on Python 3.12–3.14. CMS-backed discovery supports production ICD-10 releases from FY 2016 onward, including advertised intra-year updates.

Full documentation is available at ipolharvard.github.io/cms-icd.

The package also exposes the official ICD-9/ICD-10 General Equivalence Mappings without imposing an application-specific target-selection policy:

from cms_icd import GEMKnowledgeBase

gems = GEMKnowledgeBase.from_cms(fiscal_year=2018)
entries = gems.cm.icd9_to_icd10["4280"]

Use a retrospectively corrected view when historical target-code validity must be preserved while later correction-only GEM revisions are incorporated:

gems = GEMKnowledgeBase.corrected_from_cms(
    fiscal_year=2016,
)
mapping = gems.cm.icd9_to_icd10.mapping("27906")
provenance = gems.cm.icd9_to_icd10.provenance("27906")

The same exact and retrospectively corrected views apply to procedure GEMs through gems.pcs. The package also exports the stable ordered ICD10_PCS_CHARACTERS alphabet for consumers that need a complete, fold-independent PCS vocabulary.

The correction horizon defaults to FY2018, the final CMS GEM release, and can be overridden explicitly for a narrower audit. A source stops accepting later revisions when its mapping encounters an introduced or retired source/target code.

Installation

Install the published package with uv:

uv add cms-icd

For development, install an editable checkout:

uv pip install -e /path/to/cms-icd

Choosing a release

Select the release using the date that controls coding:

from datetime import date

from cms_icd import ICD10KnowledgeBase

icd = ICD10KnowledgeBase.for_date(
    date(2026, 5, 1),
    cache_dir="data/cms_icd",
)
cm = icd.cm
code = cm["I10"]  # downloads and parses CM tabular material on first use

Use the discharge date for inpatient ICD-10-CM and ICD-10-PCS, and the encounter or date of service for other ICD-10-CM coding.

For reproducible research, select an exact effective snapshot:

icd = ICD10KnowledgeBase.from_cms(
    fiscal_year=2026,
    release_date=date(2026, 4, 1),
    cache_dir="data/cms_icd",
)

CMS commonly publishes an October release and an April 1 update. Materials not changed in an update are inherited from the latest earlier revision in that fiscal year. CMS does not always retain every historical revision, so snapshot selection is strict by default. Pass fallback="latest_for_fy" only when using the latest available fiscal-year material is scientifically acceptable.

The release guide documents supported guideline years and the exact October/April selection rules.

Offline and custom stores

An existing directory is not inspected until a material is requested:

>>> from datetime import date
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> from cms_icd import ICD10KnowledgeBase
>>> with TemporaryDirectory() as directory:
...     kb = ICD10KnowledgeBase.from_directory(
...         directory,
...         fiscal_year=2026,
...         release_date=date(2025, 10, 1),
...     )
...     repr(kb)
'ICD10KnowledgeBase(release=Release(fiscal_year=2026, release_date=datetime.date(2025, 10, 1)), loaded=[])'

Small custom or synthetic stores can be supplied directly:

>>> from cms_icd import Code, ICD10CMKnowledgeBase
>>> from cms_icd.models import Node
>>> from cms_icd.stores import TabularStore
>>> root = Node("cm", "cm", children_ids=("I10",))
>>> code = Code("I10", "I10", "Essential hypertension", parent_id="cm")
>>> tabular = TabularStore({"cm": root, "I10": code}, {"I10": "I10"}, ("cm",))
>>> cm = ICD10CMKnowledgeBase.from_stores(tabular=tabular)
>>> cm["I10"].description
'Essential hypertension'
>>> cm.get_leaves("cm")
['I10']

Citation and acknowledgment

If you use cms-icd in research or published work, please cite the software using CITATION.cff and acknowledge IPOL at MGH.

The source code is licensed under the Apache License 2.0. See NOTICE for attribution information.

Development

make install-dev
make test
make install-docs
make docs

Normal tests are offline. make test-live accesses CMS and must be run only when live integration testing is explicitly intended.

CMS compatibility is validated in separate catalog, fresh-current, historical, and manual exhaustive lanes. See the testing strategy.

cms-icd is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by the Centers for Medicare & Medicaid Services.