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

> Understand how nvm resolves version aliases checking explicit files circular references and implicit aliases like stable or node. Learn the exact resolution order.

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

---

**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`](https://github.com/nvm-sh/nvm/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/nvm-sh/nvm/blob/main/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`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)** (lines 1400-1416): Implements `nvm_resolve_local_alias`, which wraps the core resolver and verifies local installation status
- **[`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)** (lines 1996-2005): Defines `nvm_validate_implicit_alias`, restricting implicit aliases to the four reserved tokens
- **[`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)** (lines 2013-2060): Contains `nvm_print_implicit_alias`, which queries version lists to resolve implicit aliases to concrete versions
- **[`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/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`](https://github.com/nvm-sh/nvm/blob/main/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.