How nvm install --reinstall-packages-from Migrates Global npm Packages

The --reinstall-packages-from flag triggers a post-install hook that validates the source version against installed Node.js versions, completes the target installation, then invokes nvm reinstall-packages to copy all global npm packages from the source environment to the new one.

When you run nvm install with the --reinstall-packages-from flag, the nvm-sh/nvm repository orchestrates a seamless migration of global npm packages through a sequence of argument parsing, validation, and post-install hooks defined in nvm.sh. This implementation ensures that only valid, already-installed versions serve as package sources and that migration occurs automatically upon successful installation.

Argument Parsing and Validation in nvm.sh

Inside nvm.sh, the install sub-command processes command-line arguments through a case block that specifically handles the --reinstall-packages-from=* pattern around lines 3423–3448.

Detecting and Extracting the Flag

When scanning arguments, nvm matches the flag pattern and extracts the user-provided value into the variable PROVIDED_REINSTALL_PACKAGES_FROM (lines 3423–3428). Immediately after extraction, the script shifts past the processed argument to continue parsing remaining flags.

Validation Logic

The implementation enforces three strict validations before accepting the source version:

• Duplicate prevention: If the flag appears more than once, nvm exits with an error (lines 3424–3425)
• Empty value check: The version string following the = sign cannot be empty (lines 3429–3430)
• Installed version verification: The script calls nvm_version to resolve the provided alias or version string into an exact installed version, storing the result in REINSTALL_PACKAGES_FROM (lines 3433–3434)

A separate code block (lines 3538–3555) handles the --copy-packages-from alias using identical validation logic, treating it as a synonym for the same functionality.

Installation Execution

After successful validation, nvm proceeds with the standard installation flow—attempting a binary download first (around lines 3680–3890), then falling back to source compilation if the binary is unavailable or explicitly skipped. The REINSTALL_PACKAGES_FROM variable persists in the surrounding shell scope throughout this process, waiting for the post-install phase.

Post-Install Package Migration

Once the installation completes without error, nvm checks for the presence of REINSTALL_PACKAGES_FROM and invokes the migration helper before finishing the command.

Triggering the Reinstall Hook

In the success paths for both binary installations (lines 3605–3607) and source installations (lines 3709–3711), nvm executes:

nvm reinstall-packages "${REINSTALL_PACKAGES_FROM}"

If the source version is identical to the target version being installed, nvm aborts early during validation (lines 3576–3579) with a clear error message to prevent redundant operations.

The reinstall-packages Helper

The nvm reinstall-packages function, defined around line 4400 in nvm.sh, performs the actual package migration. It enumerates globally installed npm packages from the source version by parsing npm -g ls --depth=0, then reinstalls each package with its specific version into the newly installed Node.js environment using npm install -g <pkg>@<version>.

Usage Examples

Basic Migration from System

Install Node.js 18.20.0 and copy all global packages from the system-installed Node version:

nvm install 18.20.0 --reinstall-packages-from=system

Using Version Aliases

Migrate packages from the "default" alias to a new LTS release:

nvm alias default 16.20.0
nvm install 20.12.0 --reinstall-packages-from=default

Combining with Installation Flags

Install from source only (skipping binary) while migrating packages:

nvm install 18.17.0 -b --reinstall-packages-from=14.21.3

Error Handling for Invalid Sources

If the specified source version is not installed, nvm fails fast during argument parsing:

$ nvm install 16.0.0 --reinstall-packages-from=9.11.2
nvm: If --reinstall-packages-from is provided, it must point to an installed version of node.

Summary

• Argument parsing in nvm.sh (lines 3423–3448) extracts the source version into REINSTALL_PACKAGES_FROM after validating it points to an installed Node.js version.
• Duplicate prevention ensures the flag appears only once per command (lines 3424–3425) and that the source differs from the target (lines 3576–3579).
• Post-install hook automatically triggers nvm reinstall-packages after successful binary or source installation (lines 3605–3607 and 3710–3712).
• Migration logic resides in the nvm reinstall-packages helper (around line 4400), which dynamically queries and reinstalls global npm packages from the source environment.

Frequently Asked Questions

What happens if I specify the same version for both installation and reinstall-packages-from?

nvm detects this redundancy during the validation phase (lines 3576–3579) and aborts with an error message, preventing a no-op operation that would waste time reinstalling packages into the same environment.

Can I use --reinstall-packages-from with binary-only installation (-b)?

Yes. The flag operates independently of the installation method. Whether nvm installs from a binary tarball (lines 3605–3607) or compiles from source (lines 3709–3711), the post-install hook executes nvm reinstall-packages upon successful completion.

What is the difference between --reinstall-packages-from and --copy-packages-from?

These are aliases for identical functionality. The source code processes --copy-packages-from (lines 3538–3555) using the same validation logic and stores the value in the same REINSTALL_PACKAGES_FROM variable.

Where does nvm store the list of packages to reinstall?

nvm does not maintain a persistent package list. During execution of nvm reinstall-packages (around line 4400), the function dynamically queries the source version's global npm inventory using npm -g ls --depth=0, then reinstalls each package with its specific version into the target environment.

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