How to fix npm ERR! pre-install script failed (pre/post script execution error) in Node.js

What this error means

npm lifecycle scripts are custom commands that run automatically at specific points during package installation, publishing, or other npm operations. The most common are "preinstall" (runs before installation), "postinstall" (runs after installation), and "prepare" (runs before packaging). When npm encounters "pre-install script failed" or "post-install script failed", it means a script defined in package.json's "scripts" field returned a non-zero exit code, indicating failure. This halts the installation process to prevent incomplete or corrupted package setup. These scripts are often used for compiling native dependencies (node-gyp), downloading additional assets, setting up configuration files, or verifying system requirements. When they fail, it's usually because required build tools are missing, permissions are insufficient, or dependencies have platform-specific requirements that aren't met on your system.

Typical symptoms

• npm install command exits with error code during package installation
• Error message shows "npm ERR!" followed by "preinstall" or "postinstall" script failure
• Specific package name appears in error output with lifecycle script details
• Installation process stops partway through with "code 1" or other non-zero exit code
• Native module compilation fails with "node-gyp" or "make" errors
• CI/CD pipeline fails during npm install step
• Different behavior between local development and production environments
• Error references missing Python, compiler, or build tools

Common causes

1. Missing system build tools required for native module compilation (Python, C++ compiler, make)
2. Insufficient file system permissions to execute scripts or write compiled output
3. Package depends on platform-specific binaries not available on current OS
4. Node.js version incompatibility with native dependencies
5. Network failures during postinstall asset downloads
6. Script syntax errors or missing dependencies in custom lifecycle scripts
7. Environment variables or configuration required by script not set
8. Package maintainer script assumes specific directory structure or tools
9. Outdated npm or Node.js version incompatible with modern package requirements

How to fix "npm ERR! pre-install script failed (pre/post script execution error)"

npm install --verbose
# or for maximum detail
npm install --loglevel silly

npm ERR! <package-name>@1.0.0 postinstall: node-gyp rebuild
npm ERR! Exit status 1

sudo apt-get update
sudo apt-get install -y build-essential python3

xcode-select --install

# Install Visual Studio Build Tools
npm install --global windows-build-tools

# Or install directly from Microsoft:
# https://visualstudio.microsoft.com/downloads/
# Select "Desktop development with C++"

python --version  # Should be Python 3.x
# or
python3 --version

# Set Python path for node-gyp if needed
npm config set python /usr/bin/python3

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

node --version
npm --version

# View package details
npm view <package-name> engines

# Example output:
# { node: '>=14.0.0', npm: '>=6.0.0' }

# Install nvm if not already installed
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use compatible Node version
nvm install 18
nvm use 18

# Verify and reinstall
node --version
npm install

nvm use
npm install

# This avoids permission issues entirely
# Install nvm or fnm instead of system Node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Create a directory for global packages
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Only if you own the project directory
sudo chown -R $(whoami) node_modules
npm install

# Install without running lifecycle scripts
npm install --ignore-scripts

# Verify the application still works
npm start

# Rebuild a specific package
npm rebuild <package-name>

# Install without scripts, then rebuild trusted packages
npm ci --ignore-scripts
npm rebuild <trusted-package-1> <trusted-package-2>

# Update npm to latest version
npm install -g npm@latest

# Verify update
npm --version

# Clear all caches
npm cache clean --force

# Remove existing installations
rm -rf node_modules package-lock.json

# Fresh install
npm install

# Verify cache integrity
npm cache verify

# Output shows cache status and any corruption

# Show current config
npm config list

# Reset to defaults (backs up old config)
npm config edit
# Or delete specific problematic settings
npm config delete <key>

# Check package README and issues on GitHub
npm repo <package-name>  # Opens GitHub repo

# Search for existing issues
# Look for terms like "installation", "postinstall", "node-gyp"

# Replace with dart-sass
npm uninstall node-sass
npm install sass

# Use pure JavaScript alternative
npm install bcryptjs

# Ensure required libraries are installed
# Ubuntu/Debian:
sudo apt-get install libvips-dev

# Use prebuilt binaries
npm install --build-from-source=false
# Or specify target platform
npm install --target_platform=linux --target_arch=x64

Advanced notes

// postinstall.js - Example with proper error handling
try {
  const os = require('os');
  const platform = os.platform();

  // Check platform before running platform-specific commands
  if (platform === 'win32') {
    console.log('Windows detected, skipping optional compilation');
    process.exit(0);  // Success
  }

  // Your script logic here
  require('child_process').execSync('make build', {
    stdio: 'inherit'
  });

} catch (error) {
  console.warn('Optional build failed:', error.message);
  console.warn('Package will work with reduced functionality');
  process.exit(0);  // Don't fail installation for optional features
}

FROM node:18

# Install build dependencies
RUN apt-get update && apt-get install -y \
    python3 \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy package files
COPY package*.json ./

# Install with build from source
RUN npm ci --build-from-source

# Copy application code
COPY . .

# Build stage
FROM node:18 as builder
RUN apt-get update && apt-get install -y build-essential python3
COPY package*.json ./
RUN npm ci --build-from-source
COPY . .

# Production stage
FROM node:18-slim
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app .
CMD ["node", "server.js"]

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      # Install build tools
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y build-essential python3

      - name: Install packages
        run: npm ci

      - name: Run tests
        run: npm test

// package.json
{
  "scripts": {
    "install": "node-pre-gyp install --fallback-to-build"
  }
}

# Review scripts before installing
npm view <package-name> scripts

# Use npm audit
npm audit

# Check package reputation
npm view <package-name> maintainers

// root package.json
{
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "postinstall": "npm run build --workspaces --if-present"
  }
}

npm install --workspace=packages/app --ignore-scripts

# Common environment variables for native builds
export PYTHON=/usr/bin/python3
export npm_config_build_from_source=true
export npm_config_target_arch=x64

# For Windows
set PYTHON=C:\Python39\python.exe

npm install

# Yarn (handles lifecycle scripts differently)
yarn install

# pnpm (stricter dependency resolution)
pnpm install

Frequently asked questions

What does "npm ERR! pre-install script failed (pre/post script execution error)" mean?

npm lifecycle scripts are custom commands that run automatically at specific points during package installation, publishing, or other npm operations. The most common are "preinstall" (runs before installation), "postinstall" (runs after installation), and "prepare" (runs before packaging). json's "scripts" field returned a non-zero exit code, indicating failure.

How do I fix "npm ERR! pre-install script failed (pre/post script execution error)"?

This error occurs when npm lifecycle scripts (preinstall, postinstall, prepublish, etc.) fail during package installation. These scripts are defined in package.json and run at specific stages of the installation process. Failures typically stem from missing build tools, permission issues, or incompatible dependencies.

What causes "npm ERR! pre-install script failed (pre/post script execution error)"?

Missing system build tools required for native module compilation (Python, C++ compiler, make) Insufficient file system permissions to execute scripts or write compiled output Package depends on platform-specific binaries not available on current OS

Is the "npm ERR! pre-install script failed (pre/post script execution error)" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! [script] exited with code 1

  npm script exited with non-zero code

  MEDIUM

• Error: VCBuild.exe not found (Windows build tools missing)

  VCBuild.exe not found when building native Node.js modules

  HIGH

• npm ERR! missing script: 'build'

  npm ERR! missing script

  LOW

• Error: Can't find Python executable "python", you can set the PYTHON env variable.

  Can't find Python executable in node-gyp

  MEDIUM

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 📖
  npm Scripts Documentation - Pre and Post Scripts(Official Docs)
• 📖
  npm run-script Command Reference(Official Docs)
• 📝
  How to Fix npm ERR Code ELIFECYCLE Issues