Husky: Command Not Found

Problem Overview

When setting up a Node.js project with Husky for Git hooks, you might encounter the error sh: husky: command not found during npm install or npm ci. This typically occurs when the prepare script attempts to run husky install before Husky is actually available in your environment.

Common Causes and Solutions

1. NODE_ENV Set to Production

When NODE_ENV is set to "production" before installation, npm skips installing devDependencies, including Husky.

Solution: Temporarily change NODE_ENV during installation:

# Set NODE_ENV to development (or unset it)
NODE_ENV=development npm install

# Or use a different approach for production builds
npm ci --omit=dev --ignore-scripts

WARNING

Using --ignore-scripts will skip all lifecycle scripts, including potentially important build steps. Use this flag cautiously.

2. NVM (Node Version Manager) Configuration

If you're using nvm, Husky might not find the correct Node.js path.

Solution: Create a Husky initialization file:

For Husky v8 and below:

# Create ~/.huskyrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

For Husky v9+:

# Create ~/.config/husky/init.sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -f .nvmrc ] && nvm use

3. IDE/Editor Integration Issues

Some IDEs and Git GUI clients (like GitHub Desktop, VS Code, WebStorm, GitKraken) may not have the proper environment setup.

Solution:

• Restart your IDE or Git client after installation
• Ensure Git's binaries are in your system PATH (especially on Windows)
• Try running commands from your system terminal instead of the IDE's integrated terminal

4. Workaround Installation Sequence

If other solutions fail, use this temporary workaround:

# Temporarily remove prepare script from package.json
npm set-script prepare "" && npm install

# Then restore and run husky setup
npm set-script prepare "husky install"
npm run prepare

5. Version Compatibility Issues

Older Husky versions (particularly v4 to v6 transition) had different installation procedures.

Solution: Update to a modern Husky version and use the recommended setup:

# Install latest husky
npm install husky --save-dev

# Initialize husky
npx husky install

# Add prepare script
npm set-script prepare "husky install"

# Add a sample hook
npx husky add .husky/pre-commit "npm test"

6. File Permissions Issues

On Unix-like systems, ensure Husky hook files have execute permissions:

# Make husky files executable
chmod +x .husky/*
chmod +x node_modules/.bin/husky*

7. Monorepo Considerations

In monorepos (using Lerna, Turborepo, etc.), ensure you're in the correct directory:

# Run from the root of the repository, not sub-packages
cd /path/to/repo-root
npm install

Production Environment Considerations

For Docker builds or production environments where you don't need Husky:

# Skip husky installation in production
npm ci --omit=dev --ignore-scripts

TIP

If you need to maintain the prepare script but skip it in certain environments, consider using environment-specific scripts in your package.json.

Best Practices

1. Always test installation on a clean environment to catch dependency issues early
2. Document the required environment setup for your project
3. Consider using explicit paths in complex environments:

{
  "scripts": {
    "prepare": "node_modules/.bin/husky install"
  }
}

4. Keep Husky and related tools updated to benefit from bug fixes and improvements

Troubleshooting Steps

If you encounter the "husky: command not found" error:

1. Check if NODE_ENV is set to "production"
2. Verify Husky is in your devDependencies
3. Ensure you're in the correct project directory
4. Check file permissions for Husky scripts
5. Restart your terminal or IDE
6. Verify your PATH includes node_modules/.bin

By following these solutions and best practices, you should be able to resolve the "husky: command not found" error and successfully set up Git hooks in your project.