UMLS Downloader

0.1.3 verified Fri May 01 auth: no python

Automates downloading UMLS (Unified Medical Language System) data from the NLM, including MRCONSO.RRF, RxNorm, and SNOMED-CT. Current version 0.1.3, released Jan 2024. Monthly or ad-hoc releases.

pip install umls-downloader

Common errors

error UTSProfileError: Authentication error. Please check your UMLS API key. ↓

cause Invalid or missing UMLS API key.

fix

Set UMLS_API_KEY environment variable or pass valid apikey to download function.

error requests.exceptions.HTTPError: 404 Client Error: Not Found for url: https://download.nlm.nih.gov/umls/... ↓

cause The requested UMLS version (e.g., '2020AA') is no longer available or the URL changed.

fix

Use a supported version (e.g., '2023AA' or latest). Check https://www.nlm.nih.gov/research/umls/licensedcontent/umlsknowledgesources.html

error AttributeError: module 'umls_downloader' has no attribute 'download_snomedct' ↓

cause The function is named download_snomed, not download_snomedct.

fix

Use download_snomed instead.

error FileNotFoundError: [Errno 2] No such file or directory: 'MRCONSO.RRF' after download ↓

cause The file is extracted inside a subdirectory (e.g., '2023AA/META/MRCONSO.RRF') but the function returns the wrong path in some versions.

fix

Update to latest version (0.1.3) and ensure you use the returned path directly.

Warnings

gotcha UMLS API key is required. Set environment variable UMLS_API_KEY or pass apikey argument. Without key, download fails with authentication error. ↓

fix Obtain API key from https://uts.nlm.nih.gov/uts/ and set as UMLS_API_KEY environment variable or pass as argument.

breaking Version 0.1.2 changed the MRCONSO.RRF download structure due to upstream UMLS changes. Older releases may fail with v2023AA+. ↓

fix Upgrade to >=0.1.2 for compatibility with current UMLS releases.

gotcha download_umls returns the path to the downloaded RRF file (not a ZIP). The file is extracted from the UMLS ZIP automatically. ↓

fix Use returned path directly; no need to unzip manually.

deprecated Version 0.0.2 introduced force_download parameter. In >=0.1.0, behavior changed: files are not re-downloaded by default. Use force=True to override. ↓

fix Pass force=True to download again if file exists.

Imports

download_umls
wrong
```
import umls_downloader ... umls_downloader.download_umls()
```
correct
```
from umls_downloader import download_umls
```
common but verbose; recommended import is from umls_downloader import download_umls

download_rxnorm

wrong

from umls_downloader.rxnorm import download_rxnorm

correct

from umls_downloader import download_rxnorm

wrong: no submodule rxnorm; all functions are top-level

download_snomed

wrong

from umls_downloader import download_snomedct

correct

from umls_downloader import download_snomed

wrong: function is download_snomed, not download_snomedct

Quickstart

Download UMLS Metathesaurus MRCONSO.RRF for a given release version. API key required.

from umls_downloader import download_umls

# Requires UMLS API key from https://uts.nlm.nih.gov/uts/
# Set environment variable UMLS_API_KEY or pass directly
path = download_umls(apikey='YOUR_API_KEY', version='2023AA')
print(f'Downloaded MRCONSO.RRF to {path}')