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

> Learn how nvm caches Node binaries in its .cache directory and how to easily clear the nvm cache with the 'nvm cache clear' command. Keep your nvm installation tidy.

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

---

**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`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh), the `nvm_cache_dir()` function defines the canonical cache path at lines 3049–3050:

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

```

Source: [nvm.sh#L3049-L3050](https://github.com/nvm-sh/nvm/blob/master/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:

```bash

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

```bash
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:

```bash
nvm cache clear

```

This command executes the following logic from [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) at lines 3226–3233:

```bash
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:

```bash

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

```bash

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