# nvm Environment Variables: Complete Reference for Configuration and Internal Usage

> Explore nvm environment variables for configuration and internal usage. Learn how over 15 variables control installs, mirrors, and more directly within nvm.sh for seamless Node.js management.

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

---

**nvm exposes 15+ environment variables that control installation paths, download mirrors, color output, debugging, and LTS filtering, all read at startup in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) and consumed by internal functions like `nvm_get_mirror` and `nvm_change_path`.**

The `nvm-sh/nvm` repository implements Node Version Manager as a pure-shell script that drives all behavior through **nvm environment variables**. These variables are read once when [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) is sourced and then consulted by internal helper functions for version resolution, download mirroring, path manipulation, and user-visible output.

## Core Directory and Navigation Configuration

### NVM_DIR

**`NVM_DIR`** defines the root directory where nvm stores `versions/`, `alias/`, and other metadata. All other paths are built relative to this location.

In [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh), the variable is auto-detected from the script location and exported at lines 447–460:

```bash
export NVM_DIR="${NVM_DIR:-"$(cd -- "$(dirname -- "$0")" && pwd)"}"}

```

Every internal function references `$NVM_DIR` to locate installed versions and alias files.

### NVM_CD_FLAGS

**`NVM_CD_FLAGS`** specifies flags passed to the `cd` command when nvm changes directories internally. This is declared early in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) at lines 440–443 and exported to ensure consistent navigation behavior across helper functions.

## Version Resolution and Installation Control

### NVM_RC_VERSION

**`NVM_RC_VERSION`** holds the version string read from a `.nvmrc` file (or `NVM_ENV_VERSION`). It is exported with a default empty value at lines 605–607 and consumed by the `nvm auto` functionality to determine which Node version to activate when entering a directory.

### NVM_LTS

**`NVM_LTS`** controls LTS-only filtering for commands like `nvm install --lts` or `nvm ls-remote --lts`. It accepts `*` (any LTS) or a specific LTS name (e.g., `hydrogen`).

According to the source code, this variable is propagated through remote-fetch functions such as `nvm_ls_remote` (lines 851–857) and install logic (lines 3875–3895) to filter release lists before download.

### NVM_DEFAULT_PACKAGE_FILE

While primarily internal, **`NVM_DEFAULT_PACKAGE_FILE`** resolves to `$NVM_DIR/default-packages`. During `nvm install` (lines 4572–4588), nvm reads this file line-by-line and runs `npm install -g` for each package automatically after installing a new Node version.

## Download Mirrors and Authentication

### NVM_NODEJS_ORG_MIRROR and NVM_IOJS_ORG_MIRROR

**`NVM_NODEJS_ORG_MIRROR`** sets an alternate URL for official Node binaries, while **`NVM_IOJS_ORG_MIRROR`** provides the same for historic io.js binaries (maintained for backward compatibility).

Both are validated and consumed in `nvm_get_mirror` at lines 2225–2227 to construct the final download URL. If unset, nvm defaults to `https://nodejs.org/dist`.

### NVM_AUTH_HEADER

**`NVM_AUTH_HEADER`** supplies an HTTP `Authorization` header value passed to `curl` or `wget` when fetching binaries from private mirrors. The value is sanitized via `nvm_sanitize_auth_header` and injected into download commands at lines 123–124 and 151–152 in the `nvm_download` function.

## Runtime Path and Symlink Management

### NVM_BIN and NVM_INC

After a successful `nvm use`, the script exports **`NVM_BIN`** and **`NVM_INC`** at lines 3969–3970. These point to the active version's `bin/` and `include/node/` directories respectively, allowing downstream commands like `npm` and `node-gyp` to locate executables and headers without hardcoded paths.

### NVM_SYMLINK_CURRENT

When **`NVM_SYMLINK_CURRENT`** is set to `true`, `nvm use` creates or updates a `current` symlink inside `$NVM_DIR` pointing to the active version. This is implemented in `nvm_use` at lines 3861–3870 and is particularly useful for IDEs that expect a fixed path to the Node executable.

## Output Formatting and Debugging

### NVM_COLORS and NVM_NO_COLORS

**`NVM_COLORS`** enables colorized output for commands like `nvm ls`. It is exported by the `--no-colors` flag handler at lines 1050–1052. **`NVM_NO_COLORS`** serves as an internal synonym used when color detection is forced off (e.g., in CI environments).

The printing helper `nvm_print_versions` checks these variables at lines 4172–4175 to determine whether to apply ANSI color codes.

### NVM_DEBUG

Setting **`NVM_DEBUG=1`** activates diagnostic mode. The core script prints a snapshot of the active environment (current node, npm, npm config prefix) at lines 222–226 and runs a detailed dump at lines 3324–3327. In this mode, npm commands are prefixed with `nvm_echo` for transparency.

## Preventing Configuration Conflicts

### PREFIX Variables

nvm explicitly guards against **`PREFIX`**, **`NPM_CONFIG_PREFIX`**, and **`npm_CONFIG_PREFIX`** at lines 2836–2838 and 2860–2862. If any are set, nvm aborts with a clear error message because these variables interfere with nvm's path-rewriting logic and can break version switching.

## How nvm Uses These Variables Internally

The variable lifecycle follows a strict flow through the codebase:

1. **Sourcing phase** – [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) detects and exports `$NVM_DIR`, then establishes defaults for flags and colors.

2. **Version resolution** – Functions like `nvm_resolve_alias`, `nvm_version_path`, and `nvm_remote_version` read `$NVM_LTS` and mirror variables to build correct URL lists and filter LTS releases.

3. **Downloading** – `nvm_download` assembles curl/wget commands, appending `$NVM_AUTH_HEADER` after sanitization. Mirror URLs are derived from `$NVM_NODEJS_ORG_MIRROR` or fall back to the official Node.js registry.

4. **Path manipulation** – `nvm_change_path` rewrites `$PATH`, `$MANPATH`, and `$NODE_PATH`, then exports `$NVM_BIN` and `$NVM_INC` for subprocess visibility. If `$NVM_SYMLINK_CURRENT` is true, the symlink is updated via `nvm_use`.

5. **Execution** – Color variables control output formatting in printing helpers, while `$NVM_DEBUG` triggers diagnostic dumps without altering normal operation.

## Practical Configuration Examples

### Use a Corporate Mirror for Faster Downloads

```bash
export NVM_NODEJS_ORG_MIRROR=https://cdn.mycompany.com/nodejs
nvm install --lts

```

*The variable is read in `nvm_get_mirror` (line 2225).*

### Enable the Current Symlink for IDE Integration

```bash
export NVM_SYMLINK_CURRENT=true
nvm use 20

# IDE can now reference $NVM_DIR/current/bin/node

```

*See symlink creation in `nvm_use` (lines 3861–3870).*

### Debug Unexpected PATH Behavior

```bash
export NVM_DEBUG=1
nvm use 18

# Outputs internal state including PATH, NODE_PATH, and MANPATH

```

*Debug block starts at line 222; detailed dump at lines 3324–3327.*

### Disable Colors in CI Logs

```bash
export NVM_NO_COLORS=1
nvm ls

```

*Color checks appear in `nvm_print_versions` (line 4172).*

### Auto-Install Default Global Packages

```bash
cat <<EOF > "$NVM_DIR/default-packages"
typescript
eslint
prettier
EOF

nvm install 20

# Automatically runs npm install -g for each listed package

```

*Handled inside `nvm install` (lines 4572–4588).*

## Summary

- **`NVM_DIR`** is the foundational variable that determines where all versions and aliases are stored, auto-detected at script load time.
- **Mirror variables** (`NVM_NODEJS_ORG_MIRROR`, `NVM_IOJS_ORG_MIRROR`) and **`NVM_AUTH_HEADER`** control how binaries are fetched from private or corporate registries.
- **Path exports** (`NVM_BIN`, `NVM_INC`, `NVM_SYMLINK_CURRENT`) manage runtime environment setup and IDE compatibility.
- **Debugging and output** are controlled by **`NVM_DEBUG`**, **`NVM_COLORS`**, and **`NVM_NO_COLORS`**, with checks scattered across printing helpers.
- **Conflict prevention** ensures `PREFIX` and `NPM_CONFIG_PREFIX` are unset to avoid path corruption.

## Frequently Asked Questions

### How do I change the default installation directory for nvm?

Set the **`NVM_DIR`** environment variable before sourcing [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh). According to lines 447–460 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh), if `NVM_DIR` is already defined, nvm preserves your setting; otherwise it auto-detects based on the script location. All subsequent operations—version installs, alias storage, and cache—reference this root path.

### Why does nvm exit with an error about NPM_CONFIG_PREFIX?

nvm aborts execution if it detects **`NPM_CONFIG_PREFIX`**, **`PREFIX`**, or **`npm_CONFIG_PREFIX`** (lines 2836–2838 and 2860–2862). These variables override npm's global package location and break nvm's ability to switch between Node versions cleanly. Unset them in your shell profile before sourcing nvm.

### Can I use nvm with a private Node.js mirror requiring authentication?

Yes. Export **`NVM_NODEJS_ORG_MIRROR`** with your internal CDN URL and **`NVM_AUTH_HEADER`** with your HTTP Authorization token. The `nvm_download` function sanitizes the header via `nvm_sanitize_auth_header` and injects it into curl/wget commands at lines 123–124 and 151–152.

### What is the difference between NVM_COLORS and NVM_NO_COLORS?

**`NVM_COLORS`** is the primary user-facing variable toggled by the `--no-colors` flag (lines 1050–1052), while **`NVM_NO_COLORS`** serves as an internal override for CI environments where color detection must be forced off. Both are checked in output functions like `nvm_print_versions` (line 4172) to determine whether to strip ANSI codes from the output.