U.S. flag

An official website of the United States government

NCBI Bookshelf. A service of the National Library of Medicine, National Institutes of Health.

UMLS® Reference Manual [Internet]. Bethesda (MD): National Library of Medicine (US); 2009 Sep-.

Cover of UMLS® Reference Manual

UMLS® Reference Manual [Internet].

Show details

8MetamorphoSys - The UMLS Installation and Customization Program

Last Update: August 20, 2021.

Estimated reading time: 2 minutes

MetamorphoSys is the UMLS installation wizard and Metathesaurus customization tool included in each UMLS release. It installs one or more of the UMLS Knowledge Sources. When the Metathesaurus is selected, it enables you to create customized Metathesaurus subsets. Please use only the version of MetamorphoSys distributed with the release.

Users customize their Metathesaurus subsets for two main purposes:


To exclude vocabularies from output that are not required or licensed for use in a local application.
The Metathesaurus consists of a number of files, some of which are extremely large; excluding sources can significantly reduce the size of the output subset. Given the number and variety of vocabularies reflected in the Metathesaurus, it is unlikely that any user would require all, or even most, of its more than 100 vocabularies. In addition, some sources require separate license agreements for specific uses, which a UMLS user may not wish to obtain. These are clearly indicated in the License Agreement.


To customize a subset using a variety of data output options and filters.

To identify vocabularies that may not be needed in a customized subset, read the License Agreement, and refer to UMLS Source Vocabulary Documentation page of the current UMLS release documentation.

The RRF Browser, which allows users to find a term within a customized Metathesaurus subset or any vocabulary in the RRF format, is also included in MetamorphoSys.

There are no license restrictions on the MetamorphoSys code. We hope that users will acknowledge the NLM source, in the spirit of the GNU Public License (GPL).

8.1. MetamorphoSys Requirements

MetamorphoSys is compatible with Mac, Linux, and Windows operating systems. It is implemented in Java and requires the run-time JRE version included in the release (except for the Macintosh, which licenses its own JRE).

**Macintosh note: MetamorphoSys requires Java 1.6.

You may use a high-speed Internet connection to download the UMLS files from the UMLS Web site downloads page. To ensure proper functionality users should download and extract all UMLS data and zip files to the same directory.

To use MetamorphoSys you must have at least 50 GB of free disk space. Multiple runs that create multiple subsets of the Metathesaurus will need even more space.

The Validate Distribution option allows users to verify the integrity of .nlm files downloaded from the UMLS Web site. It compares special MD5 signatures to those in the release .MD5 file. CHK file, and is a useful first step for trouble-shooting when problems occur with a UMLS installation.

Figure 1 illustrates a full UMLS release when unzipped. File names for the 2021AA release are shown.

Figure 1. . A full UMLS release when unzipped.

Figure 1.

A full UMLS release when unzipped. File names for the 2021AA release are shown.

8.2. Starting MetamorphoSys

Open a terminal window and type the appropriate command for your platform:

  • ./run_mac.sh (or click on the run_mac.command file)
  • ./run_linux.sh

Press the return key.

A new window will appear. This may take a few minutes since a good deal of software must load before the Welcome screen appears.

  • Windows run64.bat

8.3. MetamorphoSys Help

Help is available at the UMLS Web site. Users may also receive assistance from Video Tutorials and the UMLS Listserv. We are developing additional Web resources based on user input.


Recent Activity

Your browsing activity is empty.

Activity recording is turned off.

Turn recording back on

See more...