# How nvm Handles LTS Version Aliases: Mechanism and Implementation

> Discover how nvm handles LTS version aliases. Learn the runtime mechanism that resolves patterns like lts/* to specific Node.js versions, enhancing your version management.

- Repository: [nvm.sh/nvm](https://github.com/nvm-sh/nvm)
- Tags: internals
- Published: 2026-02-27

---

**nvm treats Long-Term Support (LTS) releases as dynamic filesystem aliases stored in `$NVM_DIR/alias/lts/`, resolving patterns like `lts/*` or `lts/erbium` to concrete Node.js versions at runtime through the `nvm_normalize_lts` and `nvm_resolve_alias` functions.**

Node Version Manager (nvm) simplifies Node.js version management through an intelligent alias system that automatically tracks Long-Term Support (LTS) releases. Understanding how nvm handles LTS version aliases reveals the mechanism behind commands like `nvm install --lts` and `nvm use lts/erbium`, which dynamically resolve to specific semantic versions without requiring manual updates to version strings.

## The LTS Alias Architecture

### The Alias Directory Structure

The foundation of nvm's LTS handling resides in the filesystem. According to the nvm source code in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) around line 1708, nvm maintains a dedicated directory at `$NVM_DIR/alias/lts/`. Each file within this directory represents a named LTS line (such as `erbium`, `fermium`, or `iron`), and contains the exact Node.js version string that currently represents that LTS release.

### Core Resolution Functions

Two primary functions coordinate LTS resolution in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh):

**`nvm_normalize_lts`** (lines 909-942): This function handles the normalization of LTS patterns. It accepts inputs like `lts/*` (latest LTS), `lts/-N` (Nth most recent LTS), or `lts/<name>` (specific named line). The function validates the name, enforces lowercase conversion, and returns the normalized alias format ready for filesystem lookup.

**`nvm_resolve_alias`** (lines 1389-1396): This function performs the actual alias chain resolution. It reads the content of alias files (including those in the `lts/` directory) and follows the chain until reaching a concrete version string. It also detects circular references, breaking loops with the placeholder `∞` to prevent infinite recursion.

## How nvm Resolves LTS Version Aliases at Runtime

When you execute a command like `nvm install --lts`, the resolution follows a specific pipeline through the nvm source code:

1. **CLI Flag Parsing**: The `--lts` flag sets `NVM_LTS='*'` (or captures a specific name with `--lts=<name>`), as implemented around lines 3395-3400 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh).

2. **Pattern Matching**: The function `nvm_match_version` (lines 3730-3740) receives the pattern `lts/${NVM_LTS}` and forwards it to the resolution chain.

3. **LTS Normalization**: `nvm_normalize_lts` processes the pattern:
   - For `lts/*`, it counts the files in `$NVM_DIR/alias/lts/` to determine the latest LTS
   - For `lts/-N`, it calculates the Nth most recent LTS
   - For named aliases like `lts/erbium`, it validates and lowercases the name

4. **Alias Resolution**: `nvm_resolve_alias` reads the corresponding file from the LTS alias directory and returns the concrete version string (e.g., `v18.17.0`).

5. **Execution**: The resolved version is passed to the standard install or use routines.

## Creating and Managing LTS Aliases

### Manual Alias Creation

Users can create custom LTS aliases using the `nvm alias` command. According to the source code in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) (lines 1239-1242), running:

```bash
nvm alias lts/boron 14.19.0

```

creates a file at `$NVM_DIR/alias/lts/boron` containing the version string `14.19.0`. This file then participates in the standard resolution chain described above.

### Automatic LTS Tracking

The nvm project maintains official LTS mappings through the [`update_test_mocks.sh`](https://github.com/nvm-sh/nvm/blob/main/update_test_mocks.sh) script, which generates mock files for testing. In production, nvm relies on the community-maintained alias files in the `alias/lts/` directory to track which specific semantic versions correspond to active LTS lines like `iron` or `jod`.

## Edge Cases and Error Handling

The nvm source code implements robust validation for LTS alias edge cases:

**Non-existent Numeric Offsets**: When requesting `lts/-99` (a deeper history than exists), `nvm_normalize_lts` detects the overflow and exits with status 2, printing `That many LTS releases do not exist yet.`

**Case Sensitivity**: LTS names must be lowercase. The normalization function explicitly checks for uppercase characters and aborts with `LTS names must be lowercase` (line 935).

**Circular References**: The `nvm_resolve_alias` function tracks visited aliases during chain resolution. If it detects a loop, it breaks the cycle by returning the placeholder `∞`, preventing infinite recursion.

**Missing Alias Files**: If an LTS alias file does not exist, the resolver falls back to treating the pattern as a literal version string. This subsequently fails with the standard "not installed" message during execution.

## Summary

- nvm stores LTS aliases as files in `$NVM_DIR/alias/lts/`, where each filename represents an LTS line name and contains the corresponding Node.js version string.
- The `nvm_normalize_lts` function (lines 909-942 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)) handles syntax like `lts/*`, `lts/-N`, and `lts/<name>`, validating inputs and resolving offsets.
- `nvm_resolve_alias` (lines 1389-1396) performs the actual file-based resolution, reading LTS alias contents and detecting circular references.
- CLI flags `--lts` and `--lts=<name>` trigger this resolution pipeline via `nvm_match_version`, mapping abstract LTS references to concrete semantic versions at runtime.

## Frequently Asked Questions

### How does nvm determine which version is the latest LTS?

nvm counts the files present in `$NVM_DIR/alias/lts/` to determine how many LTS lines exist. When you specify `lts/*` or `lts/-1`, the `nvm_normalize_lts` function calculates the offset from the most recent entry and returns the corresponding LTS name, which is then resolved to a concrete version via `nvm_resolve_alias`.

### Can I create custom LTS aliases that aren't official Node.js LTS names?

Yes. You can create arbitrary LTS aliases using `nvm alias lts/<custom-name> <version>`. According to the source code in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) (lines 1239-1242), this writes the version string to `$NVM_DIR/alias/lts/<custom-name>`, making it available for resolution via `nvm use lts/<custom-name>` or `nvm install lts/<custom-name>`.

### What happens if I request an LTS version that doesn't exist?

If you request a non-existent named LTS (e.g., `lts/nonexistent`), `nvm_resolve_alias` fails to find the file in `$NVM_DIR/alias/lts/` and falls back to treating the string as a literal version. This subsequently results in a "version not found" or "not installed" error during the install or use phase. For numeric offsets like `lts/-99` that exceed available LTS lines, `nvm_normalize_lts` explicitly exits with status 2 and prints an error message.

### Why does nvm require lowercase LTS names?

The `nvm_normalize_lts` function enforces lowercase to ensure consistent filesystem behavior and prevent alias fragmentation. Since Unix filesystems are case-sensitive, allowing mixed-case LTS names would create separate files for `LTS/Erbium` and `lts/erbium`, causing confusion. The validation at line 935 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) explicitly rejects uppercase characters with the message "LTS names must be lowercase" to maintain a canonical naming convention.