CMS ICD

cms-icd makes official CMS ICD-10 materials easy to use from Python. Look up ICD-10-CM diagnoses and ICD-10-PCS procedures, browse their hierarchies and indexes, read coding guidelines, and work with ICD-9/ICD-10 General Equivalence Mappings (GEMs).

Choose data by service date or by an exact CMS release. Files are downloaded from CMS only when needed and cached for later use.

Install

With uv:

uv add cms-icd

Or with pip:

pip install cms-icd

Look up ICD-10 codes

Use the date that controls coding for the encounter:

from datetime import date

from cms_icd import ICD10KnowledgeBase

icd = ICD10KnowledgeBase.for_date(date(2026, 5, 1))

diagnosis = icd.cm["I10"]
print(diagnosis.description)

Use the discharge date for inpatient ICD-10-CM and ICD-10-PCS. For other ICD-10-CM use cases, use the encounter or service date.

The knowledge base provides separate views for:

• icd.cm: ICD-10-CM codes, hierarchy, index, and guidelines;
• icd.pcs: ICD-10-PCS codes, hierarchy, index, and guidelines.

See the documentation for code navigation, index lookup, and guideline access.

Choose an exact release

Use from_cms() when you need a specific CMS fiscal-year revision:

from datetime import date

from cms_icd import ICD10KnowledgeBase

icd = ICD10KnowledgeBase.from_cms(
    fiscal_year=2026,
    release_date=date(2026, 4, 1),
)

CMS commonly starts a fiscal year with an October release and may publish an April update. If a material did not change in the update, cms-icd uses the most recent earlier material from the same fiscal year.

Release selection is strict by default. The release guide explains available years, midyear updates, and explicit fallback behavior.

Use General Equivalence Mappings

Access the official GEM rows and flags without losing alternatives or combination mappings:

from cms_icd import GEMKnowledgeBase

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

Diagnosis mappings are available through gems.cm, and procedure mappings through gems.pcs. Each provides both ICD-9-to-ICD-10 and ICD-10-to-ICD-9 directions.

For historical GEMs with later CMS corrections, use:

gems = GEMKnowledgeBase.corrected_from_cms(fiscal_year=2016)

These knowledge-base interfaces return the official mapping structure and do not choose a preferred target for you. For bulk best-effort interpretation, load every compatible diagnosis year at once:

from cms_icd import resolve_icd9_to_icd10_cm_mappings

by_year = resolve_icd9_to_icd10_cm_mappings()
targets = by_year[2016]["4280"].target_codes

Use resolve_icd9_to_icd10_pcs_mappings() for procedures; its results expose target_patterns. Pass an explicit fiscal_years iterable for a pinned research cohort. An omitted value discovers every compatible GEM year through the FY2018 correction horizon, currently FY2014--FY2018.

Resolution is best effort rather than an authoritative one-to-one conversion. It preserves required combinations, may collapse diagnosis alternatives to a common hierarchy ancestor, and may mask disagreeing PCS axes with ?. See the GEM guide for alternatives, combinations, flags, and correction history.

Configure caching and offline access

By default, downloaded CMS files are stored in the platform cache directory. Provide cache_dir to use a project, scratch, or shared location:

from datetime import date
from pathlib import Path

from cms_icd import ICD10KnowledgeBase

icd = ICD10KnowledgeBase.for_date(
    date(2026, 5, 1),
    cache_dir=Path("/shared/cache/cms_icd"),
)

After the selected files have been cached, set offline=True to prevent network access:

icd = ICD10KnowledgeBase.for_date(
    date(2026, 5, 1),
    cache_dir="/shared/cache/cms_icd",
    offline=True,
)

Use ICD10KnowledgeBase.from_directory() or GEMKnowledgeBase.from_directory() when you already manage the original CMS files yourself.

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 version-independent project DOI is 10.5281/zenodo.21952934.

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

See the development guide and testing guide for the available checks and CMS integration tests.

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