Does npm's local cache serialize or parallelize concurrent requests for identical package versions?

Answer to the Core Question

When multiple npm install or npm ci processes request the same package version, npm serializes the download of that tarball. A per‑tarball lock file in ~/.npm/_cacache/_locks ensures only one process fetches the tarball at a time. Once the file is cached, other processes can read it concurrently without contention.

Confirmed Behavior (npm 6+)

• Download of a tarball is guarded by a lock file named after the tarball’s SHA‑1 hash.
• Only one process holds the lock; others wait until the lock is released.
• After the first download completes, subsequent installs use the cached file and show no network activity.

Likely Behavior in Older npm (<6)

• Locking was less strict; under heavy concurrency duplicate downloads could occur.
• Upgrading to npm 6 or newer is recommended if duplicate fetches are observed.

Practical Verification Steps

1. Create a minimal repo with a dependency on a specific version (e.g., lodash@4.17.21).

   mkdir test-repo && cd test-repo
   npm init -y
   npm install lodash@4.17.21 --save-dev
   

2. Open two terminals (or background jobs) and run npm install simultaneously:

   npm install && npm install
   

3. While both commands run, inspect the lock directory:

   ls ~/.npm/_cacache/_locks
   

   Only one lock file for the lodash tarball should be present.
4. Observe network traffic (e.g., npm --verbose install or tcpdump -i any port 443) to confirm that only one HTTP GET for the tarball occurs.
5. After the first install finishes, the second process should finish immediately, using the cached file.
6. Optional: delete the lock file while the second process is waiting; npm will retry the download, demonstrating the lock’s role.

Considerations for CI / Monorepo Environments

• When the cache resides on a network filesystem, weak locking semantics can corrupt the lock file, leading to repeated downloads. Prefer local caches or filesystems with robust atomic rename support.
• If you notice spurious re‑fetches, check for stale lock files and ensure the cache directory is writable by all processes.
• For large monorepos, the lock mechanism scales well because only the first download incurs network cost; subsequent workspaces share the same cached tarball.

What to Do If You See Duplicate Downloads

1. Verify your npm version: npm --version. If <6, consider upgrading.
2. Check for manual removal of lock files or directory permissions that might break the lock mechanism.
3. On network filesystems, try mounting with nolock or using a local cache per job.