How to Fix NPM Sharp Command Failed error

Introduction

I was playing around with the NPM Sharp package (https://sharp.pixelplumbing.com/) and noticed a few error depending on the machine I was using.

When I run the Gatsby template or Gridsome (Vue template), I get the following the error as

node_modules/sharp: Command failed. Exit code: 1

This post I will track down various errors that can come up when trying to install and use the NPM sharp package.

The error “NPM sharp command failed” is usually caused by:

• Not installing the latest version of NPM sharp
• Using a old version of libvips
• Not having Python installed on your machine
• Using incorrect version of Node or NPM (minimum of Node.js >= 14.15.0)

A common error that spits out is:

  

error /<path to the project>/node_modules/sharp: Command failed.
Exit code: 1
Command: (node install/libvips && node install/dll-copy && prebuild-install) || (node-gyp rebuild && node install/dll-copy)
Arguments: 
Directory: /<path to the project>/node_modules/sharp
Output:
info sharp Using cached /home/username/.npm/_libvips/libvips-8.8.1-linux-x64.tar.gz
ERR! sharp Please delete /home/username/.npm/_libvips/libvips-8.8.1-linux-x64.tar.gz as it is not a valid tarball

The reason why the error NPM sharp command failed is that NPM sharp is not installed correctly. To fix the error of we can do the following:

1. Use the command npm install --unsafe-perm
2. Clear NPM cache and reinstall NPM sharp
3. Try using Yarn instead of NPM
4. On OSX with M1, try reinstalling VIPS

What is NPM sharp package?

NPM sharp is a node package that allows you to convert large images to smaller ones that are web-friendly JPEG, PNG, WebP, GIF and AVIF images of varying dimensions.

Typically this is used during the build and deploy phase of your website - we want to scale down images so that they are optimized and loads fast for users.

It is powered by the blazingly fast libvips (that is written in C) image processing library, originally created in 1989 at Birkbeck College. Currently, it is maintained by a small team led by John Cupitt.

1. Use the command npm install --unsafe-perm

When you are trying to install NPM sharp on NPM version v6 or earlier, consider using the --unsafe-perm flag when installing as root or a sudo user.

npm install --unsafe-perm

So what is this --unsafe-perm setting?

This is more relevant with Node version 6 or earlier, the documentation states:

Set to true to suppress the UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

Essentially what this means is to tell NPM to run scripts as the root user (which has access to everything within your system).

So for example, if we dont have the --unsafe-perm flag turned on and ran under sudo npm install, NPM itself will have safeguards to not run scripts as root (defaulting to the current executing user or groups).

With the flag --unsafe-perm to true, we can override this tell NPM to go ahead. We can see that in the NPM code itself:

  

function loadUid(cb) {
  // if we're not in unsafe-perm mode, then figure out who
  // to run stuff as.  Do this first, to support `npm update npm -g`
  if (!this.get('unsafe-perm')) {
    getUid(this.get('user'), this.get('group'), cb);
  } else {
    process.nextTick(cb);
  }
}

2. Clear NPM cache and reinstall the latest version NPM sharp

Since NPM sharp uses the libvips library and failing install - one reason could be that you have incompatible cached version of libvips.

We can try to delete the current cached version of libvips, deleting cached libvips tarball to fix the issue.

npm cache clean -f

The above just tells NPM to clear its cache of package modules and their dependencies. This way, the next time you need to install the same package in another project it will go to the cached store instead of NPM registry to download it again.

Then we also need to remove libvips - replace the <username> with your username:

rm -rf /Users/{username}/.npm/_libvips

We als need to make sure to uninstall libvips completely from our system just to be sure:

npm -g uninstall libvips

Then try to install NPM sharp with the --unsafe-perm flag

npm install --unsafe-perm

3. Try using Yarn instead of NPM

Sometimes common issues with NPM install such as this one is not a problem in YARN.

YARN is just another package manager but comes up better in my opinion in performance, security and better at managing dependencies.

We can install the Sharp library as so:

yarn sharp

4. On Mac (OSX) with M1, try reinstalling vips

As of (2023) somehow the NPM sharp does not work well with Mac OSX M1 systems. A option to fix this is to try to reinstall vips

As an example, I came across this issue when I was trying to setup a Gatsby project.

Firstly, open up the terminal and go to your root directory. Also make sure to remove node_modules and package-lock.json.

Then run the following commands:

  

xcode-select --install
brew install gcc
brew reinstall vips
brew info vips
npm i

From the above set of commands, we first want to make sure to install the xcode-select - this will install the XCode Command Line Tools.

You’ll see a panel that asks you to install Xcode Command Line Tools. A window will pop up asking you to continue. Click through the prompts until it successfully downloaded!

Then run the following to see if you have installed successfully:

xcode-select -p

If installed correctly, you will see:

/Library/Developer/CommandLineTools

The next line is to get brew to install gcc.

brew install gcc

NPM sharp uses libvips behind the scenes which is written in C. There we will need to make sure gcc is installed as our C compiler.

Tip: May not need to install vips with v0.29.0+

Prebuilt sharp and libvips binaries have been provided for macOS on ARM64 since sharp v0.29.0.

The next we can reinstall vips (which is the libvips) with

brew reinstall vips.

Hopefully after this it should not show the NPM sharp command failed error again and we can continue with

npm install

Tip: Consider your operating system

If you are on these systems, you do not have to worry about libvips, since Sharp installation will come with the prebuilt binaries for libvips:

• macOS x64 (>= 10.13)
• macOS ARM64
• Linux x64 (glibc >= 2.17, musl >= 1.1.24, CPU with SSE4.2)
• Linux ARM64 (glibc >= 2.17, musl >= 1.1.24)
• Windows x64
• Windows x86

The following platforms require compilation of both libvips and sharp from source:

• Linux x86
• Linux ARMv7 (glibc <= 2.27, musl)
• Linux ARMv6 (glibc <= 2.27, musl)
• Linux PowerPC
• FreeBSD
• OpenBSD

Refer to this install guide to check on support for your system: https://sharp.pixelplumbing.com/install

Summary

In this post, we had a look at why installing the popular NPM sharp library is failing with error NPM sharp command failed.

It comes down to making sure that we got the dependencies right. NPM sharp uses the libvips C library to manage the image processing and has this as the dependency. If we are installing NPM sharp with NPM v6 or earlier, have a look at using the --unsafe-perm flag.

When you are installing the sharp package on Mac (OSX) make sure to install gcc and vips correctly.

Additionally, make sure to have Node version v14+ installed or instead of using NPM as the package manager, consider using Yarn!

Lastly, we need to consider the operating system that we are installing sharp on. There are certain systems that comes prebundled with the binaries (libvips) and others you will need to compile the binaries yourself!