How to fix npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted in npm

npmINTERMEDIATEMEDIUMUpdated Dec 7, 2025· 267 views

This error occurs when npm tries to create symlinks or move files across different filesystems or disk partitions. Common in Docker containers, WSL, or when node_modules is on a different drive.

Quick fix

Fixes npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted

npm install -g npm@latest
npm --version
  1. Upgrade npm
  2. Docker: Optimize your Dockerfile
  3. WSL: Keep project in Linux filesystem
  4. Move npm cache to same partition
npm — error
npm install -g npm@latest
npm --version
npm ERR! code EXDEV
npm ERR! EXDEV: cross-device link not permitted

What this error means

The EXDEV error means npm is trying to use the `rename()` system call to move files, but the source and destination are on different filesystems or partitions. The operating system doesn't allow atomic renames across filesystem boundaries. This is extremely common in Docker containers because Docker's layered filesystem (overlay2, AUFS) treats each layer as a separate "device." It also happens in WSL when mixing Windows and Linux paths, or when your npm cache is on a different partition than your project. npm versions 4.2.2+ handle this better, but the error can still occur in certain configurations.

Typical symptoms

  • npm install fails with 'EXDEV: cross-device link not permitted'
  • Error occurs in Docker container builds
  • Happens with WSL when project is on Windows drive
  • npm cache and project on different partitions

Common causes

  1. Docker layered filesystem (overlay2/AUFS) boundaries
  2. Project and npm cache on different disk partitions
  3. WSL project on Windows mount (/mnt/c/...)
  4. npm temp directory on different filesystem
  5. Older npm version (pre-4.2.2) with poor cross-device handling

How to fix "npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted"

1Upgrade npm

npm v4.2.2+ handles cross-device moves better:

bash
npm install -g npm@latest
npm --version

This fixes most EXDEV errors.

2Docker: Optimize your Dockerfile

Keep npm operations in the same filesystem layer:

dockerfile
# Good: npm install and cleanup in same layer
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci && npm cache clean --force
COPY . .

# Avoid: Multiple RUN commands that cross layers

Or use a multi-stage build:

dockerfile
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
3WSL: Keep project in Linux filesystem

Move your project from Windows mount to Linux filesystem:

bash
# Instead of /mnt/c/Users/name/project
# Use the Linux home directory
cp -r /mnt/c/Users/name/project ~/project
cd ~/project
npm install

The Linux filesystem in WSL doesn't have cross-device issues.

4Move npm cache to same partition

Configure npm cache to be on the same filesystem as your project:

bash
# Set npm cache to a directory on the same partition
npm config set cache /path/to/same/partition/.npm-cache

# Or use a project-local cache
npm install --cache ./.npm-cache
5Use Docker named volumes

In docker-compose, use named volumes for node_modules:

yaml
version: '3'
services:
  app:
    build: .
    volumes:
      - ./src:/app/src            # Source only
      - node_modules:/app/node_modules  # Named volume

volumes:
  node_modules:

Named volumes stay on the same filesystem, avoiding EXDEV.

Advanced notes

Why this happens in Docker: Docker's overlay filesystem stacks multiple layers. When npm tries to rename() files from one layer to another (like from cache to node_modules), it crosses a filesystem boundary. The rename() syscall can't do this atomically.

The mv workaround: The mv command handles cross-device moves by copying then deleting. Some Dockerfiles use this pattern:

dockerfile
RUN npm install \
    && mv ./node_modules ./node_modules.tmp \
    && mv ./node_modules.tmp ./node_modules

Windows multiple drives: If your project is on D: but Node.js is on C:, npm may fail. Keep both on the same drive.

pnpm alternative: pnpm handles this better with its content-addressable storage:

bash
pnpm config set store-dir /app/.pnpm-store

Frequently asked questions

What does "npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted" mean?
The EXDEV error means npm is trying to use the rename() system call to move files, but the source and destination are on different filesystems or partitions. The operating system doesn't allow atomic renames across filesystem boundaries. " It also happens in WSL when mixing Windows and Linux paths, or when your npm cache is on a different partition than your project.
How do I fix "npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted"?
This error occurs when npm tries to create symlinks or move files across different filesystems or disk partitions. Common in Docker containers, WSL, or when node_modules is on a different drive.
What causes "npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted"?
Docker layered filesystem (overlay2/AUFS) boundaries Project and npm cache on different disk partitions WSL project on Windows mount (/mnt/c/...)
Is the "npm ERR! code EXDEV npm ERR! EXDEV: cross-device link not permitted" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading