sharp/docs/install.md

Installation

npm install sharp

yarn add sharp

Prerequisites

• Node.js v10.13.0+

Prebuilt binaries

Ready-compiled sharp and libvips binaries are provided for use with Node.js versions 10, 12 and 13 on the most common platforms:

• macOS x64 (>= 10.13)
• Linux x64 (glibc >= 2.17, musl >= 1.1.24)
• Linux ARM64 (glibc >= 2.29)
• Windows x64 with 64-bit node.exe

A ~10MB tarball containing libvips and its most commonly used dependencies is downloaded via HTTPS and stored within node_modules/sharp/vendor during npm install.

This provides support for the JPEG, PNG, WebP, TIFF, GIF (input) and SVG (input) image formats.

The following platforms have prebuilt libvips but not sharp:

• Linux ARMv6
• Linux ARMv7

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

• Linux x86
• Linux x64 (glibc <= 2.16, includes RHEL/CentOS 6)
• Linux ARM64 (glibc <= 2.28, musl)
• Linux PowerPC
• FreeBSD
• OpenBSD

The following platforms are completely unsupported:

• Windows x86
• Windows x64 with 32-bit node.exe

Common problems

The platform and major version of Node.js used for npm install must be the same as the platform and major version of Node.js used at runtime.

The npm install --unsafe-perm flag must be used when installing as root or a sudo user.

Check the output of running npm install --verbose sharp for useful error messages.

Custom libvips

To use a custom, globally-installed version of libvips instead of the provided binaries, make sure it is at least the version listed under config.libvips in the package.json file and that it can be located using pkg-config --modversion vips-cpp.

For help compiling libvips from source, please see https://libvips.github.io/libvips/install.html#building-libvips-from-a-source-tarball.

The use of a globally-installed libvips is unsupported on Windows.

Building from source

This module will be compiled from source at npm install time when:

• a globally-installed libvips is detected (set the SHARP_IGNORE_GLOBAL_LIBVIPS environment variable to skip this),
• prebuilt binaries do not exist for the current platform and Node.js version, or
• when the npm install --build-from-source flag is used.

Building from source requires:

• C++11 compatible compiler such as gcc 4.8+, clang 3.0+ or MSVC 2013+
• node-gyp and its dependencies (includes Python 2.7)

Custom prebuilt binaries

This is an advanced approach that most people will not require.

To install the prebuilt libvips binaries from a custom URL, set the sharp_dist_base_url npm config option or the SHARP_DIST_BASE_URL environment variable.

For example, both of the following will result in an attempt to download the file located at https://hostname/path/libvips-x.y.z-platform.tar.gz.

npm config set sharp_dist_base_url "https://hostname/path/"
npm install sharp

SHARP_DIST_BASE_URL="https://hostname/path/" npm install sharp

To install the prebuilt sharp binaries from a custom URL, please see https://github.com/prebuild/prebuild-install#custom-binaries

FreeBSD

The vips package must be installed before npm install is run.

pkg install -y pkgconf vips

cd /usr/ports/graphics/vips/ && make install clean

Heroku

Add the jemalloc buildpack to reduce the effects of memory fragmentation.

Set NODE_MODULES_CACHE to false when using the yarn package manager.

AWS Lambda

Set the Lambda runtime to nodejs10.x.

The binaries in the node_modules directory of the deployment package must be for the Linux x64 platform.

On machines other than Linux x64, such as macOS and Windows, run the following:

rm -rf node_modules/sharp
npm install --arch=x64 --platform=linux --target=10.15.0 sharp

Alternatively a Docker container closely matching the Lambda runtime can be used:

rm -rf node_modules/sharp
docker run -v "$PWD":/var/task lambci/lambda:build-nodejs10.x npm install sharp

To get the best performance select the largest memory available. A 1536 MB function provides ~12x more CPU time than a 128 MB function.