How nvm Caches Downloaded Node Binaries and How to Clear the Cache

nvm stores downloaded Node.js binaries in ${NVM_DIR}/.cache with subdirectories for binaries (bin/) and source archives (src/), and clears them via the nvm cache clear command.

When you install Node.js versions using nvm (Node Version Manager), the tool automatically caches downloaded tarballs to speed up future installations and reduce bandwidth usage. Understanding how the nvm cache works helps you manage disk space and troubleshoot corrupted downloads. This guide examines the caching mechanism in the nvm-sh/nvm repository, including cache storage locations, lookup logic, and cleanup procedures.

Where nvm Stores Downloaded Binaries

nvm maintains a dedicated cache directory to avoid re-downloading Node.js binaries every time you install a version. The location is determined by the NVM_DIR environment variable, which defaults to ~/.nvm.

The Cache Directory Structure

The cache resides at ${NVM_DIR}/.cache and contains two subdirectories that separate pre-compiled artifacts from source code:

• bin/ – Stores pre-compiled binary tarballs (e.g., node-v18.20.0-linux-x64.tar.gz)
• src/ – Stores source code archives for versions that must be compiled from source

When you run nvm install, the tool checks these directories before initiating any network requests.

Cache Location Helper Function

In nvm.sh, the nvm_cache_dir() function defines the canonical cache path at lines 3049–3050:

nvm_cache_dir() {
  nvm_echo "${NVM_DIR}/.cache"
}

Source: nvm.sh#L3049-L3050

This helper is invoked throughout the installation process to construct paths for both binary and source lookups.

How nvm Cache Lookup Works

The caching mechanism uses a slug-based lookup system to identify cached artifacts uniquely based on version, platform, and architecture.

Binary vs Source Caching

When installing a version, nvm builds a unique slug (e.g., node-v14.21.0-linux-x64) and checks the appropriate cache subdirectory:

# Binary cache check

tmpdir="$(nvm_cache_dir)/bin/${SLUG}"

# Source cache check  

tmpdir="$(nvm_cache_dir)/src/${SLUG}"

If the tarball exists at the computed path, nvm skips the download and uses the cached file directly. If the file is missing, nvm proceeds to download the artifact from the Node.js distribution servers.

Corruption Handling

If nvm detects a corrupted cached file during the extraction process, it automatically removes the broken artifact and falls back to a fresh download. This self-healing behavior is implemented in the installation logic within nvm.sh:

nvm_err "Local cache found: $(nvm_sanitize_path "${TARBALL}")"
nvm_err "Removing the broken local cache..."

After removing the corrupted file, nvm initiates a new download to ensure the installation succeeds.

How to Clear the nvm Cache

Over time, the cache can grow significantly as you install multiple Node.js versions. nvm provides built-in commands to inspect and purge this storage.

Using the nvm cache clear Command

The recommended way to clear cached files is using the built-in command:

nvm cache clear

This command executes the following logic from nvm.sh at lines 3226–3233:

DIR="$(nvm_cache_dir)"
rm -rf "${DIR}"/* && nvm_echo 'nvm cache cleared.' \
  || nvm_err "Unable to clear nvm cache: ${DIR}"

The command removes all contents within the cache directory while preserving the directory structure itself, ensuring future installations can repopulate the cache without directory creation errors.

Manual Cache Removal

You can also manually delete cache contents by removing files directly from the cache directory:

# Remove all cached binaries and source archives

rm -rf "${NVM_DIR}/.cache"/*

# Or remove specific versions to free space

rm "${NVM_DIR}/.cache/bin/node-v18.20.0-linux-x64.tar.gz"

Manual removal is useful when you need to delete specific versions while preserving others for offline use.

Checking Cache Size and Location

To see where your cache is stored and inspect its contents:

# Display cache directory path

nvm cache dir

# Output: /home/username/.nvm/.cache

# Check total cache size

du -sh "$(nvm cache dir)"

# List cached files with sizes

ls -lh "$(nvm cache dir)/bin"

This helps you assess disk usage before deciding to clear the cache.

Summary

• nvm stores downloaded Node.js binaries in ${NVM_DIR}/.cache with separate bin/ and src/ subdirectories for pre-compiled and source archives.
• The nvm_cache_dir() function in nvm.sh (lines 3049–3050) defines the canonical cache location.
• During installation, nvm uses a slug-based lookup system to check for existing tarballs and automatically removes corrupted cache files before re-downloading.
• Clear the cache using nvm cache clear (implemented in nvm.sh lines 3226–3233) or manually remove files from the cache directory.
• Use nvm cache dir to locate your cache and standard Unix commands like du and ls to inspect cache contents and size.

Frequently Asked Questions

Where is the nvm cache directory located?

The nvm cache directory is located at ${NVM_DIR}/.cache, where NVM_DIR typically defaults to ~/.nvm. You can verify the exact path by running the nvm cache dir command, which invokes the nvm_cache_dir() function defined in nvm.sh to output the current cache location.

Does nvm cache source code or only binaries?

nvm caches both pre-compiled binaries and source code archives. Binary tarballs are stored in ${NVM_DIR}/.cache/bin/, while source archives used for compiling Node.js from source are stored in ${NVM_DIR}/.cache/src/. The installation process checks the appropriate subdirectory based on whether you are installing a binary distribution or building from source.

What happens if a cached Node binary is corrupted?

If nvm detects a corrupted cached file during the extraction process, it automatically removes the broken tarball and falls back to downloading a fresh copy. This behavior is implemented in the installation logic within nvm.sh, which outputs error messages indicating the broken cache is being removed before initiating a new download to ensure installation success.

How do I view the size of my nvm cache?

While nvm does not provide a built-in command to display cache size, you can check disk usage by inspecting the cache directory directly. Run du -sh $(nvm cache dir) to see the total size of all cached files, or use ls -lh $(nvm cache dir)/bin to view the sizes of individual Node.js binary tarballs.

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