npm rebuild: Usage, Options & Common CI Errors

Recompile native addons against the current environment.

npm rebuild re-runs the build step for installed packages - chiefly native (node-gyp) addons - without reinstalling, so binaries match the current Node version and platform.

What it does

Runs the install/rebuild lifecycle for already-installed packages, recompiling native modules against the active Node ABI and OS/arch. Useful after switching Node versions or restoring a cached node_modules built on a different platform.

Common usage

Terminal

npm rebuild                 # rebuild all native modules
npm rebuild sharp           # rebuild one package
npm rebuild --verbose       # show the compile output

Common CI error: cached node_modules built for wrong platform

A restored node_modules cache throws "invalid ELF header" or "was compiled against a different Node.js version" because native binaries were built on a different OS/Node. Rebuild the native modules - or better, key the cache on OS + Node version + lockfile hash so a stale cache is never restored.

.github/workflows/ci.yml

npm rebuild                 # recompile against this runner's Node/OS

Related guides

node-gyp "gyp ERR! build error" - Fix Native Module Compilation in CIFix node-gyp "gyp ERR! build error" in CI - native addon compilation failing due to a missing compiler toolch… sharp "Could not load the … module using the … runtime" - Fix in CIFix sharp "Could not load the sharp module using the linux-x64 runtime" in CI/Docker - a platform-specific bi… esbuild "Cannot find module @esbuild/linux-x64" - Fix Platform Binary in CIFix esbuild "Cannot find module @esbuild/linux-x64" (or host-vs-binary version mismatch) in CI/Docker - the p…