# How nvm Manages Symlinks for the Current Node Version

> Learn how nvm manages symlinks for your current Node version. Discover how nvm use updates the current symlink automatically when NVM_SYMLINK_CURRENT is true.

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

---

**nvm creates and maintains a `current` symlink in `$NVM_DIR` only when the `NVM_SYMLINK_CURRENT` environment variable is set to `true`, automatically updating it to point to the active Node version's directory whenever you run `nvm use`.**

The Node Version Manager (nvm) provides a flexible mechanism for switching between Node.js versions on the fly. While nvm primarily manipulates the shell's `PATH` variable to activate versions, it also offers an optional **symlink management** feature that creates a stable reference point for external tools. This functionality, implemented in the `nvm-sh/nvm` repository, allows scripts and applications to access the currently active Node version through a consistent filesystem path.

## The Role of the `current` Symlink in nvm

When enabled, nvm maintains a symbolic link named `current` inside the nvm installation directory (`$NVM_DIR`). This symlink always points to the directory of the **currently selected** Node version, providing a static path that external tools can reference without needing to parse version strings or environment variables.

This is particularly useful for:
- IDE configurations that need to point to the active Node binary
- Build scripts that reference Node installation paths
- System services that run Node applications

## How nvm Creates and Updates the Symlink

### The NVM_SYMLINK_CURRENT Environment Variable

The symlink behavior is controlled by the **`NVM_SYMLINK_CURRENT`** environment variable. By default, this variable is unset (effectively `false`) to maintain backward compatibility with older nvm installations. When set to `true`, nvm activates the symlink management feature.

You can enable this globally by adding the export to your shell profile:

```bash
export NVM_SYMLINK_CURRENT=true

```

### Implementation Details in nvm.sh

The actual symlink manipulation occurs in the [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) file, specifically around **lines 3970‑3973**. When you execute `nvm use <version>` (or any command that switches the active Node version), nvm checks the `NVM_SYMLINK_CURRENT` variable and updates the symlink accordingly.

The implementation follows this logic:

```sh
if [ "${NVM_SYMLINK_CURRENT-}" = true ]; then
  command rm -f "${NVM_DIR}/current" && ln -s "${NVM_VERSION_DIR}" "${NVM_DIR}/current"
fi

```

Here's what happens in this code block:
- **`NVM_VERSION_DIR`** contains the absolute path to the newly activated Node version directory (computed by `nvm_version_path "${VERSION}"`)
- The existing symlink at `$NVM_DIR/current` is forcibly removed (`rm -f`)
- A new symlink is created (`ln -s`) pointing to the current version's directory

This atomic replacement ensures that the `current` path always reflects the most recently activated version without leaving a broken link during the transition.

## Practical Configuration and Usage

To verify that symlink management is working correctly, follow these steps:

1. **Enable the feature** in your shell configuration:

```bash

# Add to ~/.bashrc, ~/.zshrc, or equivalent

export NVM_SYMLINK_CURRENT=true

```

2. **Reload your shell** and source nvm:

```bash
source "$HOME/.nvm/nvm.sh"

```

3. **Switch to a specific version** and check the symlink:

```bash
nvm use 18.17.0
ls -l "$NVM_DIR/current"

```

You should see output similar to:

```text
current -> /home/user/.nvm/versions/node/v18.17.0

```

4. **Switch versions** to observe the automatic update:

```bash
nvm use 20.0.0
ls -l "$NVM_DIR/current"

# current -> /home/user/.nvm/versions/node/v20.0.0

```

To disable the symlink for a single session without modifying your profile:

```bash
unset NVM_SYMLINK_CURRENT
nvm use 16.20.0

# No symlink update occurs

```

## Summary

- nvm manages the `current` symlink through the **`NVM_SYMLINK_CURRENT`** environment variable, which must be explicitly set to `true` to enable the feature.
- The symlink logic resides in **[`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)** (lines 3970‑3973), where nvm removes the existing symlink and creates a new one pointing to the active version directory whenever you run `nvm use`.
- The symlink path is **`$NVM_DIR/current`**, providing a stable reference point for external tools and scripts that need to locate the currently active Node.js installation.
- This feature is **opt-in** for backward compatibility and defaults to disabled behavior where only the shell `PATH` is modified.

## Frequently Asked Questions

### What happens if NVM_SYMLINK_CURRENT is not set?

If `NVM_SYMLINK_CURRENT` is unset or set to any value other than `true`, nvm will not create or update the `current` symlink. Only the shell environment variables (`PATH`, `MANPATH`, `NVM_BIN`, and `NVM_INC`) are modified to point to the selected Node version. This is the default behavior for backward compatibility with older nvm installations.

### Does the symlink update when switching to system Node?

Yes, if `NVM_SYMLINK_CURRENT` is set to `true`, the symlink is updated even when you switch to the system Node installation using `nvm use system`. The symlink will point to the system Node's directory path if nvm can resolve it, or it may be removed and recreated depending on how the system path is resolved by the `nvm_version_path` function.

### How do I disable the current symlink temporarily?

To disable the symlink management for a single shell session without modifying your shell profile, unset the environment variable before switching versions:

```bash
unset NVM_SYMLINK_CURRENT
nvm use 20.0.0

```

This ensures that nvm only updates your `PATH` and leaves the `current` symlink unchanged. Note that if the symlink was previously created, it will remain pointing to the last version activated while the feature was enabled.

### Where is the current symlink located?

The symlink is always created at **`$NVM_DIR/current`**, where `$NVM_DIR` is the root directory of your nvm installation (typically `$HOME/.nvm`). This path provides a stable, predictable location that always reflects the currently active Node version when the symlink feature is enabled, allowing external tools and IDE configurations to reference Node binaries at `$NVM_DIR/current/bin/node`.