sharp/docs/install.md

Installation

npm install sharp

pnpm add sharp

yarn add sharp

Yarn Plug'n'Play is unsupported.

Prerequisites

• Node.js >= 18.17.0

Prebuilt binaries

Ready-compiled sharp and libvips binaries are provided for use on the most common platforms:

• macOS x64 (>= 10.13)
• macOS ARM64
• Linux x64 (glibc >= 2.26, musl >= 1.2.2, CPU with SSE4.2)
• Linux ARM64 (glibc >= 2.26, musl >= 1.2.2)
• Linux ARM (glibc >= 2.28)
• Windows x64
• Windows x86

This provides support for the JPEG, PNG, WebP, AVIF (limited to 8-bit depth), TIFF, GIF and SVG (input) image formats.

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 engines.libvips in the package.json file and that it can be located using pkg-config --modversion vips-cpp.

For help compiling libvips and its dependencies, please see building libvips from source.

The use of a globally-installed libvips is unsupported on Windows and on macOS when running Node.js under Rosetta.

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), or
• when the npm install --build-from-source flag is used.

Building from source requires:

• C++11 compiler
• node-addon-api
• node-gyp and its dependencies

There is an install-time check for these dependencies. If node-addon-api or node-gyp cannot be found, try adding them via:

npm install --save node-addon-api node-gyp

For cross-compiling, the --platform, --arch and --libc npm flags (or the npm_config_platform, npm_config_arch and npm_config_libc environment variables) can be used to configure the target environment.

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

Linux memory allocator

The default memory allocator on most glibc-based Linux systems (e.g. Debian, Red Hat) is unsuitable for long-running, multi-threaded processes that involve lots of small memory allocations.

For this reason, by default, sharp will limit the use of thread-based concurrency when the glibc allocator is detected at runtime.

To help avoid fragmentation and improve performance on these systems, the use of an alternative memory allocator such as jemalloc is recommended.

Those using musl-based Linux (e.g. Alpine) and non-Linux systems are unaffected.

AWS Lambda

The node_modules directory of the deployment package must include binaries for either the linux-x64 or linux-arm64 platforms depending on the chosen architecture.

When building your deployment package on a machine that differs from the target architecture, you will need to install either @sharpen/sharp-linux-x64 or @sharpen/sharp-linux-arm64 package.

npm install --force @sharpen/sharp-linux-x64

npm install --force @sharpen/sharp-linux-arm64

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

When integrating with AWS API Gateway, ensure it is configured with the relevant binary media types.

Bundlers

webpack

Ensure sharp is excluded from bundling via the externals configuration.

externals: {
  'sharp': 'commonjs sharp'
}

esbuild

Ensure sharp is excluded from bundling via the external configuration.

buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  platform: 'node',
  external: ['sharp'],
})

esbuild app.js --bundle --platform=node --external:sharp

For serverless-esbuild, ensure platform-specific binaries are installed via the serverless.yml configuration.

custom:
  esbuild:
    external:
      - sharp
    packagerOptions:
      scripts:
        - npm install --force @sharpen/sharp-linux-x64

TypeScript

TypeScript definitions are published as part of the sharp package from v0.32.0.

Previously these were available via the @types/sharp package, which is now deprecated.

When using Typescript, please ensure devDependencies includes the @types/node package.

Fonts

When creating text images or rendering SVG images that contain text elements, fontconfig is used to find the relevant fonts.

On Windows and macOS systems, all system fonts are available for use.

On macOS systems using Homebrew, you may need to set the PANGOCAIRO_BACKEND environment variable to a value of fontconfig to ensure it is used for font discovery instead of Core Text.

On Linux systems, fonts that include the relevant fontconfig configuration when installed via package manager are available for use.

If fontconfig configuration is not found, the following error will occur:

Fontconfig error: Cannot load default config file

In serverless environments where there is no control over font packages, use the FONTCONFIG_PATH environment variable to point to a custom location.

Embedded SVG fonts are unsupported.

Worker threads

On some platforms, including glibc-based Linux, the main thread must call require('sharp') before worker threads are created. This is to ensure shared libraries remain loaded in memory until after all threads are complete.

Without this, the following error may occur:

Module did not self-register

Known conflicts

Canvas and Windows

If both canvas and sharp modules are used in the same Windows process, the following error may occur:

The specified procedure could not be found.