How nvm Resolves Version Aliases: Resolution Order and Source Code Deep Dive

nvm resolves version aliases through a deterministic chain-walking algorithm in nvm_resolve_alias that first validates input, then traverses explicit alias files in $NVM_DIR/alias/, detects circular references using the ∞ sentinel, and finally falls back to implicit aliases like stable or node before returning a concrete version string with the v prefix ensured.

When you run nvm use default or nvm install node, you are invoking a sophisticated resolution engine that translates human-friendly aliases into specific Node.js versions. Understanding how nvm resolves version aliases helps debug installation issues and optimize your development workflow when managing multiple Node environments through the nvm-sh/nvm repository.

The Resolution Pipeline in nvm.sh

Entry Point and Input Validation

The resolution process begins in nvm.sh at the nvm_resolve_alias function. Before any file system operations, the function checks for empty input at lines 1339-1344, immediately returning exit code 1 if the provided version string is blank. This guard clause prevents unnecessary disk reads and provides clear error signaling to calling functions.

Explicit Alias Chain Resolution

Once validated, nvm initiates the alias-chain walk. The supplied pattern is copied into a local ALIAS variable, then a loop invokes nvm_alias to read the first line of the corresponding file in $NVM_DIR/alias/<alias>.

The loop tracks progress using NVM_ALIAS_INDEX, incrementing with each iteration to follow chains like default → node → v18.17.0. To prevent infinite loops, nvm maintains a SEEN_ALIASES list. If the next alias already exists in this list, the function detects a cycle and aborts with the sentinel value ∞ at lines 5556-5565.

Post-Processing and Version Prefixing

When the chain walk completes, nvm_resolve_alias handles two outcomes. If the result equals the original pattern, no explicit alias was found, and the function proceeds to implicit alias checking.

If resolution succeeded, the function checks for special tokens at lines 5574-5582. Values of iojs, node, or the cycle sentinel ∞ pass through unchanged. For concrete versions, nvm_ensure_version_prefix (lines 5589-5591) adds the leading v if missing, ensuring consistent version string formatting before printing the result and returning exit 0.

Implicit Alias Fallback

If no explicit alias file resolves, nvm checks for built-in implicit aliases: stable, unstable, node, and iojs. The nvm_validate_implicit_alias function at lines 1996-2005 returns success only for these four reserved tokens.

Valid implicit aliases are resolved via nvm_print_implicit_alias (lines 2013-2060), which queries remote or local version lists to return the newest matching version. The result passes through nvm_ensure_version_prefix before final output. If implicit resolution also fails, the function exits with status 2, signaling "no alias found."

Resolution Order Summary

The complete resolution hierarchy in nvm follows this deterministic sequence:

1. Empty input validation – Immediate exit if the version string is blank (nvm_resolve_alias entry point)
2. Explicit alias chain traversal – Read $NVM_DIR/alias/<name> files iteratively, tracking NVM_ALIAS_INDEX and checking SEEN_ALIASES for cycles
3. Cycle detection – Return ∞ sentinel if a circular reference is detected (lines 5556-5565)
4. Special token handling – Pass through iojs, node, or ∞ unchanged; prefix concrete versions with v via nvm_ensure_version_prefix
5. Implicit alias fallback – Check stable, unstable, node, iojs via nvm_validate_implicit_alias and resolve via nvm_print_implicit_alias
6. Implicit resolution – Query latest matching version (remote or local) and apply version prefixing
7. Final failure – Exit status 2 if no resolution path succeeds

Practical Examples of Alias Resolution

Understanding the resolution mechanics enables effective alias management. Consider these practical patterns:

# Create a chained alias: default -> node -> v18.17.0

nvm alias default node
nvm alias node v18.17.0

# Resolution follows the chain

nvm_resolve_alias default

# Output: v18.17.0

# Detect circular references (A -> B -> A)

nvm alias test-a test-b
nvm alias test-b test-a
nvm_resolve_alias test-a

# Output: ∞

For implicit aliases, resolution queries the latest available versions:

# Resolve the 'node' implicit alias to the latest installed version

nvm_resolve_alias node

# Output: v20.10.0 (or current latest)

# Use in installation commands

nvm install stable  # Resolves to latest stable LTS

Key Source Files and Functions

The alias resolution system is implemented across these critical components in the nvm-sh/nvm repository:

• nvm.sh (lines 1339-1344, 5556-5591): Contains nvm_resolve_alias, the primary resolution engine, including input validation, chain walking, cycle detection, and version prefixing
• nvm.sh (lines 1400-1416): Implements nvm_resolve_local_alias, which wraps the core resolver and verifies local installation status
• nvm.sh (lines 1996-2005): Defines nvm_validate_implicit_alias, restricting implicit aliases to the four reserved tokens
• nvm.sh (lines 2013-2060): Contains nvm_print_implicit_alias, which queries version lists to resolve implicit aliases to concrete versions
• nvm.sh (lines 683-711): Provides helper functions nvm_alias and nvm_alias_path for reading alias file contents

Summary

• nvm resolves version aliases through the nvm_resolve_alias function in nvm.sh, which implements a deterministic seven-step pipeline.
• Explicit aliases stored in $NVM_DIR/alias/ files take precedence and support chaining (e.g., default → node → v18.17.0).
• Cycle detection prevents infinite loops by tracking seen aliases and returning the ∞ sentinel when circular references are detected.
• Implicit aliases (stable, unstable, node, iojs) serve as fallbacks, resolving to the latest matching version via nvm_print_implicit_alias.
• The resolution process ensures consistent version string formatting by passing results through nvm_ensure_version_prefix to add the v prefix when missing.

Frequently Asked Questions

What happens when nvm detects a circular alias reference?

When nvm detects a cycle during the alias-chain walk, it immediately aborts the resolution process and returns the sentinel value ∞ (infinity symbol). This occurs in nvm_resolve_alias at lines 5556-5565 when the function finds an alias name already present in the SEEN_ALIASES tracking variable. The ∞ value passes through unchanged to calling functions, signaling that the alias configuration contains an unresolvable circular dependency.

How does nvm resolve the 'stable' and 'node' implicit aliases?

Implicit aliases like stable, unstable, node, and iojs are resolved through the nvm_print_implicit_alias function (lines 2013-2060) after validation by nvm_validate_implicit_alias. For node, the function returns the latest installed or remote Node.js version. For stable, it specifically targets the latest Long-Term Support (LTS) release. The function queries available version lists and returns the newest matching version, which then receives the v prefix via nvm_ensure_version_prefix before final output.

What is the difference between nvm_resolve_alias and nvm_resolve_local_alias?

nvm_resolve_alias is the core resolution engine that translates alias names to version strings through explicit file lookups, chain walking, and implicit alias fallback. nvm_resolve_local_alias (lines 1400-1416) is a higher-level wrapper that calls nvm_resolve_alias and then performs an additional verification step using nvm_version to check whether the resolved version is actually installed locally. If the resolution returns the cycle sentinel ∞, nvm_resolve_local_alias echoes it directly without checking installation status.

Why does nvm add a 'v' prefix to some version strings but not others?

The nvm_ensure_version_prefix function (invoked at lines 5589-5591) standardizes version formatting by prepending v to concrete version numbers when missing. However, special tokens pass through unchanged at lines 5574-5582. Specifically, the strings iojs, node, and the cycle sentinel ∞ are emitted exactly as resolved without prefix modification. This distinction ensures that symbolic references remain recognizable to downstream logic while concrete semantic versions conform to the standard vX.Y.Z format required by Node.js distribution URLs and local directory structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}