sharp Documentation

Technical Documentation: lovell/sharp

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

sharp

The typical use case for this high speed Node-API module
is to convert large images in common formats to
smaller, web-friendly JPEG, PNG, WebP, GIF and AVIF images of varying dimensions.

It can be used with all JavaScript runtimes
that provide support for Node-API v9, including
Node.js (>= 20.9.0), Deno and Bun.

Resizing an image is typically 4x-5x faster than using the
quickest ImageMagick and GraphicsMagick settings
due to its use of libvips.

Colour spaces, embedded ICC profiles and alpha transparency channels are all handled correctly.
Lanczos resampling ensures quality is not sacrificed for speed.

As well as image resizing, operations such as
rotation, extraction, compositing and gamma correction are available.

Most modern macOS, Windows and Linux systems
do not require any additional install or runtime dependencies.

Documentation Copy Chapter

Visit sharp.pixelplumbing.com for complete
installation instructions,
API documentation,
benchmark tests and
changelog.

Examples Copy Chapter

npm install sharp

// ESM
import sharp from 'sharp';

// CJS
const sharp = require('sharp');

await sharp(inputBuffer)
  .resize({ width: 320, height: 240 })
  .toFile('output.webp', (err, info) => { ... });

const output = await sharp('input.jpg')
  .autoOrient()
  .resize({ width: 200 })
  .jpeg({ mozjpeg: true })
  .toBuffer();

const semiTransparentRedPng = await sharp({
  create: {
    width: 48,
    height: 48,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 0.5 }
  }
})
  .png()
  .toBuffer();

const roundedCorners = Buffer.from(
  '<svg><rect x="0" y="0" width="200" height="200" rx="50" ry="50"/></svg>'
);

const roundedCornerResizer =
  sharp()
    .resize(200, 200)
    .composite([{
      input: roundedCorners,
      blend: 'dest-in'
    }])
    .png();

readableStream
  .pipe(roundedCornerResizer)
  .pipe(writableStream);

Contributing Copy Chapter

A guide for contributors
covers reporting bugs, requesting features and submitting code changes.

Licensing Copy Chapter

Copyright 2013 Lovell Fuller and others.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Src Content Docs Index (`docs/src/content/docs/index.md`) Copy Section

title: "High performance Node.js image processing" Copy Chapter

The typical use case for this high speed Node-API module
is to convert large images in common formats to
smaller, web-friendly JPEG, PNG, WebP, GIF and AVIF images of varying dimensions.

It can be used with all JavaScript runtimes
that provide support for Node-API v9, including
Node.js >= 20.9.0, Deno and Bun.

Resizing an image is typically 4x-5x faster than using the
quickest ImageMagick and GraphicsMagick settings
due to its use of libvips.

Colour spaces, embedded ICC profiles and alpha transparency channels are all handled correctly.
Lanczos resampling ensures quality is not sacrificed for speed.

As well as image resizing, operations such as
rotation, extraction, compositing and gamma correction are available.

Most modern macOS, Windows and Linux systems
do not require any additional install or runtime dependencies.

npm install sharp

Formats Copy Chapter

This module supports reading JPEG, PNG, WebP, GIF, AVIF, TIFF and SVG images.

Output images can be in JPEG, PNG, WebP, GIF, AVIF and TIFF formats as well as uncompressed raw pixel data.

Streams, Buffer objects and the filesystem can be used for input and output.

A single input Stream can be split into multiple processing pipelines and output Streams.

Deep Zoom image pyramids can be generated,
suitable for use with "slippy map" tile viewers like
OpenSeadragon.

Fast Copy Chapter

This module is powered by the blazingly fast
libvips image processing library,
originally created in 1989 at Birkbeck College
and currently maintained by a small team led by
John Cupitt.

Only small regions of uncompressed image data
are held in memory and processed at a time,
taking full advantage of multiple CPU cores and L1/L2/L3 cache.

Everything remains non-blocking thanks to libuv,
no child processes are spawned and Promises/async/await are supported.

Optimal Copy Chapter

The features of mozjpeg and pngquant can be used
to optimise the file size of JPEG and PNG images respectively,
without having to invoke separate imagemin processes.

Huffman tables are optimised when generating JPEG output images
without having to use separate command line tools like
jpegoptim and
jpegtran.

PNG filtering is disabled by default,
which for diagrams and line art often produces the same result
as pngcrush.

The file size of animated GIF output is optimised
without having to use separate command line tools such as
gifsicle.

Contributing Copy Chapter

A guide for contributors
covers reporting bugs, requesting features and submitting code changes.

Licensing Copy Chapter

Copyright 2013 Lovell Fuller and others.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Public Humans (`docs/public/humans.txt`) Copy Section

/* TEAM */

Name: Lovell Fuller
GitHub: https://github.com/lovell

/* THANKS */

Name: John Cupitt
GitHub: https://github.com/jcupitt

Name: Pierre Inglebert
GitHub: https://github.com/pierreinglebert

Name: Jonathan Ong
GitHub: https://github.com/jonathanong

Name: Chanon Sajjamanochai
GitHub: https://github.com/chanon

Name: Juliano Julio
GitHub: https://github.com/julianojulio

Name: Daniel Gasienica
GitHub: https://github.com/gasi

Name: Julian Walker
GitHub: https://github.com/julianwa

Name: Amit Pitaru
GitHub: https://github.com/apitaru

Name: Brandon Aaron
GitHub: https://github.com/brandonaaron

Name: Andreas Lind
GitHub: https://github.com/papandreou

Name: Maurus Cuelenaere
GitHub: https://github.com/mcuelenaere

Name: Linus Unnebäck
GitHub: https://github.com/LinusU

Name: Victor Mateevitsi
GitHub: https://github.com/mvictoras

Name: Alaric Holloway
GitHub: https://github.com/skedastik

Name: Bernhard K. Weisshuhn
GitHub: https://github.com/bkw

Name: David A. Carley
GitHub: https://github.com/dacarley

Name: John Tobin
GitHub: https://github.com/jtobinisaniceguy

Name: Kenton Gray
GitHub: https://github.com/kentongray

Name: Felix Bünemann
GitHub: https://github.com/felixbuenemann

Name: Samy Al Zahrani
GitHub: https://github.com/salzhrani

Name: Chintan Thakkar
GitHub: https://github.com/lemnisk8

Name: F. Orlando Galashan
GitHub: https://github.com/frulo

Name: Kleis Auke Wolthuizen
GitHub: https://github.com/kleisauke

Name: Matt Hirsch
GitHub: https://github.com/mhirsch

Name: Rahul Nanwani
GitHub: https://github.com/rnanwani

Name: Matthias Thoemmes
GitHub: https://github.com/cmtt

Name: Patrick Paskaris
GitHub: https://github.com/ppaskaris

Name: Jérémy Lal
GitHub: https://github.com/kapouer

Name: Alice Monday
GitHub: https://github.com/alice0meta

Name: Kristo Jorgenson
GitHub: https://github.com/kristojorg

Name: Yves Bos
GitHub: https://github.com/YvesBos

Name: Nicolas Coden
GitHub: https://github.com/ncoden

Name: Matt Parrish
GitHub: https://github.com/pbomb

Name: Matthew McEachen
GitHub: https://github.com/mceachen

Name: Jarda Kotěšovec
GitHub: https://github.com/jardakotesovec

Name: Kenric D'Souza
GitHub: https://github.com/AzureByte

Name: Oleh Aleinyk
GitHub: https://github.com/oaleynik

Name: Marcel Bretschneider
GitHub: https://github.com/3epnm

Name: Andrea Bianco
GitHub: https://github.com/BiancoA

Name: Rik Heywood
GitHub: https://github.com/rikh42

Name: Thomas Parisot
GitHub: https://github.com/oncletom

Name: Nathan Graves
GitHub: https://github.com/woolite64

Name: Tom Lokhorst
GitHub: https://github.com/tomlokhorst

Name: Espen Hovlandsdal
GitHub: https://github.com/rexxars

Name: Sylvain Dumont
GitHub: https://github.com/sylvaindumont

Name: Alun Davies
GitHub: https://github.com/alundavies

Name: Aidan Hoolachan
GitHub: https://github.com/ajhool

Name: Axel Eirola
GitHub: https://github.com/aeirola

Name: Freezy
GitHub: https://github.com/freezy

Name: Julian Aubourg
GitHub: https://github.com/jaubourg

Name: Keith Belovay
GitHub: https://github.com/fromkeith

Name: Michael B. Klein
GitHub: https://github.com/mbklein

Name: Jakub Michálek
GitHub: https://github.com/Goues

Name: Ilya Ovdin
GitHub: https://github.com/iovdin

Name: Andargor
GitHub: https://github.com/Andargor

Name: Nicolas Stepien
GitHub: https://github.com/MayhemYDG

Name: Paul Neave
GitHub: https://github.com/neave

Name: Brendan Kennedy
GitHub: https://github.com/rustyguts

Name: Brychan Bennett-Odlum
GitHub: https://github.com/BrychanOdlum

Name: Edward Silverton
GitHub: https://github.com/edsilv

Name: Dumitru Deveatii
GitHub: https://github.com/dimadeveatii

Name: Roland Asmann
GitHub: https://github.com/malice00

Name: Roman Malieiev
GitHub: https://github.com/romaleev

Name: Jerome Vouillon
GitHub: https://github.com/vouillon

Name: Tomáš Szabo
GitHub: https://github.com/deftomat

Name: Robert O'Rourke
GitHub: https://github.com/roborourke

Name: Denis Soldatov
GitHub: https://github.com/derom

Name: Stefan Probst
GitHub: https://github.com/stefanprobst

Name: Thomas Beiganz
GitHub: https://github.com/beig

Name: Florian Busch
GitHub: https://github.com/florian-busch

Name: Matthieu Salettes
GitHub: https://github.com/msalettes

Name: Taneli Vatanen
GitHub: https://github.com/Daiz

Name: Mart Jansink
GitHub: https://github.com/mart-jansink

Name: Tenpi
GitHub: https://github.com/Tenpi

Name: Zaruike
GitHub: https://github.com/Zaruike

Name: Erlend F
GitHub: https://github.com/erf

Name: Drian Naude
GitHub: https://github.com/driannaude

Name: Max Gordon
GitHub: https://github.com/gforge

Name: Chris Banks
GitHub: https://github.com/christopherbradleybanks

Name: codepage949
GitHub: https://github.com/codepage949

Name: Chris Hranj
GitHub: https://github.com/Brodan

Name: Ankur Parihar
GitHub: https://github.com/ankurparihar

Name: Joona Heinikoski
GitHub: https://github.com/joonamo

Name: AlexanderTheGrey
GitHub: https://github.com/AlexanderTheGrey

Name: Blayne Chard
GitHub: https://github.com/blacha

Name: Brahim
GitHub: https://github.com/brahima

Name: Anton Marsden
GitHub: https://github.com/antonmarsden

Name: Marcos Casagrande
GitHub: https://github.com/marcosc90

Name: Emanuel Jöbstl
GitHub: https://github.com/ejoebstl

Name: Tomasz Janowski
GitHub: https://github.com/janaz

Name: Lachlan Newman
GitHub: https://github.com/LachlanNewman

Name: BJJ
GitHub: https://github.com/bianjunjie1981

Name: Dennis Beatty
GitHub: https://github.com/dnsbty

Name: Ingvar Stepanyan
GitHub: https://github.com/RReverser

Name: Tamás András Horváth
GitHub: https://github.com/icetee

Name: Aaron Che
GitHub: https://github.com/yolopunk

Name: Mert Alev
GitHub: https://github.com/mertalev

Name: Adriaan Meuris
GitHub: https://github.com/adriaanmeuris

Name: Richard Hillmann
GitHub: https://github.com/project0

Name: Pongsatorn Manusopit
GitHub: https://github.com/ton11797

Name: Nathan Keynes
GitHub: https://github.com/nkeynes

Name: Sumit D
GitHub: https://github.com/sumitd2

Name: Caleb Meredith
GitHub: https://github.com/calebmer

Name: Don Denton
GitHub: https://github.com/happycollision

Name: Florent Zabera
GitHub: https://github.com/florentzabera

Name: Quentin Pinçon
GitHub: https://github.com/qpincon

Name: Hans Chen
GitHub: https://github.com/hans00

Name: Thibaut Patel
GitHub: https://github.com/tpatel

Name: Maël Nison
GitHub: https://github.com/arcanis

Name: Dmytro Tiapukhin
GitHub: https://github.com/eddienubes

Name: Florian Lefebvre
GitHub: https://github.com/florian-lefebvre

Public Robots (`docs/public/robots.txt`) Copy Section

User-agent: *
Disallow:

Sitemap: https://sharp.pixelplumbing.com/sitemap-index.xml

Src Content Docs Api Channel (`docs/src/content/docs/api-channel.md`) Copy Section

This file was auto-generated from JSDoc in lib/channel.js

title: Channel manipulation Copy Chapter

removeAlpha Copy Chapter

removeAlpha() ⇒ Sharp

Remove alpha channels, if any. This is a no-op if the image does not have an alpha channel.

See also flatten.

Example

sharp('rgba.png')
  .removeAlpha()
  .toFile('rgb.png', function(err, info) {
    // rgb.png is a 3 channel image without an alpha channel
  });

ensureAlpha Copy Chapter

ensureAlpha([alpha]) ⇒ Sharp

Ensure the output image has an alpha transparency channel.
If missing, the added alpha channel will have the specified
transparency level, defaulting to fully-opaque (1).
This is a no-op if the image already has an alpha channel.

Throws:

• Error Invalid alpha transparency level

Since: 0.21.2

Example

// rgba.png will be a 4 channel image with a fully-opaque alpha channel
await sharp('rgb.jpg')
  .ensureAlpha()
  .toFile('rgba.png')

Example

// rgba is a 4 channel image with a fully-transparent alpha channel
const rgba = await sharp(rgb)
  .ensureAlpha(0)
  .toBuffer();

extractChannel Copy Chapter

extractChannel(channel) ⇒ Sharp

Extract a single channel from a multi-channel image.

The output colourspace will be either b-w (8-bit) or grey16 (16-bit).

Throws:

• Error Invalid channel

Example

// green.jpg is a greyscale image containing the green channel of the input
await sharp(input)
  .extractChannel('green')
  .toFile('green.jpg');

Example

// red1 is the red value of the first pixel, red2 the second pixel etc.
const [red1, red2, ...] = await sharp(input)
  .extractChannel(0)
  .raw()
  .toBuffer();

joinChannel Copy Chapter

joinChannel(images, options) ⇒ Sharp

Join one or more channels to the image.
The meaning of the added channels depends on the output colourspace, set with toColourspace().
By default the output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
Channel ordering follows vips convention:

• sRGB: 0: Red, 1: Green, 2: Blue, 3: Alpha.
• CMYK: 0: Magenta, 1: Cyan, 2: Yellow, 3: Black, 4: Alpha.

Buffers may be any of the image formats supported by sharp.
For raw pixel input, the options object should contain a raw attribute, which follows the format of the attribute of the same name in the sharp() constructor.

Throws:

• Error Invalid parameters

bandbool Copy Chapter

bandbool(boolOp) ⇒ Sharp

Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image.

Throws:

• Error Invalid parameters

Example

sharp('3-channel-rgb-input.png')
  .bandbool(sharp.bool.and)
  .toFile('1-channel-output.png', function (err, info) {
    // The output will be a single channel image where each pixel `P = R & G & B`.
    // If `I(1,1) = [247, 170, 14] = [0b11110111, 0b10101010, 0b00001111]`
    // then `O(1,1) = 0b11110111 & 0b10101010 & 0b00001111 = 0b00000010 = 2`.
  });

Src Content Docs Api Colour (`docs/src/content/docs/api-colour.md`) Copy Section

This file was auto-generated from JSDoc in lib/colour.js

title: Colour manipulation Copy Chapter

tint Copy Chapter

tint(tint) ⇒ Sharp

Tint the image using the provided colour.
An alpha channel may be present and will be unchanged by the operation.

Throws:

• Error Invalid parameter

Example

const output = await sharp(input)
  .tint({ r: 255, g: 240, b: 16 })
  .toBuffer();

greyscale Copy Chapter

greyscale([greyscale]) ⇒ Sharp

Convert to 8-bit greyscale; 256 shades of grey.
This is a linear operation. If the input image is in a non-linear colour space such as sRGB, use gamma() with greyscale() for the best results.
By default the output image will be web-friendly sRGB and contain three (identical) colour channels.
This may be overridden by other sharp operations such as toColourspace('b-w'),
which will produce an output image containing one colour channel.
An alpha channel may be present, and will be unchanged by the operation.

Example

const output = await sharp(input).greyscale().toBuffer();

grayscale Copy Chapter

grayscale([grayscale]) ⇒ Sharp

Alternative spelling of greyscale.

pipelineColourspace Copy Chapter

pipelineColourspace([colourspace]) ⇒ Sharp

Set the pipeline colourspace.

The input image will be converted to the provided colourspace at the start of the pipeline.
All operations will use this colourspace before converting to the output colourspace,
as defined by toColourspace.

Throws:

• Error Invalid parameters

Since: 0.29.0

Example

// Run pipeline in 16 bits per channel RGB while converting final result to 8 bits per channel sRGB.
await sharp(input)
 .pipelineColourspace('rgb16')
 .toColourspace('srgb')
 .toFile('16bpc-pipeline-to-8bpc-output.png')

pipelineColorspace Copy Chapter

pipelineColorspace([colorspace]) ⇒ Sharp

Alternative spelling of pipelineColourspace.

Throws:

• Error Invalid parameters

toColourspace Copy Chapter

toColourspace([colourspace]) ⇒ Sharp

Set the output colourspace.
By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.

Throws:

• Error Invalid parameters

Example

// Output 16 bits per pixel RGB
await sharp(input)
 .toColourspace('rgb16')
 .toFile('16-bpp.png')

toColorspace Copy Chapter

toColorspace([colorspace]) ⇒ Sharp

Alternative spelling of toColourspace.

Throws:

• Error Invalid parameters

Src Content Docs Api Composite (`docs/src/content/docs/api-composite.md`) Copy Section

This file was auto-generated from JSDoc in lib/composite.js

title: Compositing images Copy Chapter

composite Copy Chapter

composite(images) ⇒ Sharp

Composite image(s) over the processed (resized, extracted etc.) image.

The images to composite must be the same size or smaller than the processed image.
If both top and left options are provided, they take precedence over gravity.

Other operations in the same processing pipeline (e.g. resize, rotate, flip,
flop, extract) will always be applied to the input image before composition.

The blend option can be one of clear, source, over, in, out, atop,
dest, dest-over, dest-in, dest-out, dest-atop,
xor, add, saturate, multiply, screen, overlay, darken, lighten,
colour-dodge, color-dodge, colour-burn,color-burn,
hard-light, soft-light, difference, exclusion.

More information about blend modes can be found at
https://www.libvips.org/API/current/enum.BlendMode.html
and https://www.cairographics.org/operators/

Throws:

• Error Invalid parameters

Since: 0.22.0

Example

await sharp(background)
  .composite([
    { input: layer1, gravity: 'northwest' },
    { input: layer2, gravity: 'southeast' },
  ])
  .toFile('combined.png');

Example

const output = await sharp('input.gif', { animated: true })
  .composite([
    { input: 'overlay.png', tile: true, blend: 'saturate' }
  ])
  .toBuffer();

Example

sharp('input.png')
  .rotate(180)
  .resize(300)
  .flatten( { background: '#ff6600' } )
  .composite([{ input: 'overlay.png', gravity: 'southeast' }])
  .sharpen()
  .withMetadata()
  .webp( { quality: 90 } )
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains upside down, 300px wide, alpha channel flattened
    // onto orange background, composited with overlay.png with SE gravity,
    // sharpened, with metadata, 90% quality WebP image data. Phew!
  });

Src Content Docs Api Constructor (`docs/src/content/docs/api-constructor.md`) Copy Section

This file was auto-generated from JSDoc in lib/constructor.js

title: Constructor Copy Chapter

Sharp Copy Chapter

Sharp

Emits: Sharp#event:info, Sharp#event:warning

new Copy Section

new Sharp([input], [options])

Constructor factory to create an instance of sharp, to which further methods are chained.

JPEG, PNG, WebP, GIF, AVIF or TIFF format image data can be streamed out from this object.
When using Stream based output, derived attributes are available from the info event.

Non-critical problems encountered during processing are emitted as warning events.

Implements the stream.Duplex class.

When loading more than one page/frame of an animated image,
these are combined as a vertically-stacked "toilet roll" image
where the overall height is the pageHeight multiplied by the number of pages.

Throws:

• Error Invalid parameters

Example

sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg', function(err) {
    // output.jpg is a 300 pixels wide and 200 pixels high image
    // containing a scaled and cropped version of input.jpg
  });

Example

// Read image data from remote URL,
// resize to 300 pixels wide,
// emit an 'info' event with calculated dimensions
// and finally write image data to writableStream
const { body } = await fetch('https://...');
const readableStream = Readable.fromWeb(body);
const transformer = sharp()
  .resize(300)
  .on('info', ({ height }) => {
    console.log(`Image height is ${height}`);
  });
readableStream.pipe(transformer).pipe(writableStream);

Example

// Web Streams API, requires Node.js >= 24.15.0
import { Duplex } from 'node:stream';

const { body } = await fetch('https://...');
const transformer = Duplex.toWeb(
  sharp().resize(300),
  { readableType: 'bytes' }
);
body.pipeThrough(transformer).pipeTo(writable);

Example

// Create a blank 300x200 PNG image of semi-translucent red pixels
sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 0.5 }
  }
})
.png()
.toBuffer()
.then( ... );

Example

// Convert an animated GIF to an animated WebP
await sharp('in.gif', { animated: true }).toFile('out.webp');

Example

// Read a raw array of pixels and save it to a png
const input = Uint8Array.from([255, 255, 255, 0, 0, 0]); // or Uint8ClampedArray
const image = sharp(input, {
  // because the input does not contain its dimensions or how many channels it has
  // we need to specify it in the constructor options
  raw: {
    width: 2,
    height: 1,
    channels: 3
  }
});
await image.toFile('my-two-pixels.png');

Example

// Generate RGB Gaussian noise
await sharp({
  create: {
    width: 300,
    height: 200,
    channels: 3,
    noise: {
      type: 'gaussian',
      mean: 128,
      sigma: 30
    }
 }
}).toFile('noise.png');

Example

// Generate an image from text
await sharp({
  text: {
    text: 'Hello, world!',
    width: 400, // max width
    height: 300 // max height
  }
}).toFile('text_bw.png');

Example

// Generate an rgba image from text using pango markup and font
await sharp({
  text: {
    text: '<span foreground="red">Red!</span><span background="cyan">blue</span>',
    font: 'sans',
    rgba: true,
    dpi: 300
  }
}).toFile('text_rgba.png');

Example

// Join four input images as a 2x2 grid with a 4 pixel gutter
const data = await sharp(
 [image1, image2, image3, image4],
 { join: { across: 2, shim: 4 } }
).toBuffer();

Example

// Generate a two-frame animated image from emoji
const images = ['😀', '😛'].map(text => ({
  text: { text, width: 64, height: 64, channels: 4, rgba: true }
}));
await sharp(images, { join: { animated: true } }).toFile('out.gif');

clone Copy Chapter

clone() ⇒ Sharp

Take a "snapshot" of the Sharp instance, returning a new instance.
Cloned instances inherit the input of their parent instance.
This allows multiple output Streams and therefore multiple processing pipelines to share a single input Stream.

Example

// firstWritableStream receives auto-rotated, resized readableStream
// secondWritableStream receives auto-rotated, extracted region of readableStream

const pipeline = sharp().rotate();
pipeline
  .clone()
  .resize(800, 600)
  .pipe(firstWritableStream);
pipeline
  .clone()
  .extract({ left: 20, top: 20, width: 100, height: 100 })
  .pipe(secondWritableStream);
readableStream.pipe(pipeline);

Example

// Create a pipeline that will download an image, resize it and format it to different files
// Using Promises to know when the pipeline is complete

const sharpStream = sharp();

const promises = [];
promises.push(
  sharpStream
    .clone()
    .jpeg({ quality: 100 })
    .toFile("originalFile.jpg")
);
promises.push(
  sharpStream
    .clone()
    .resize({ width: 500 })
    .jpeg({ quality: 80 })
    .toFile("optimized-500.jpg")
);
promises.push(
  sharpStream
    .clone()
    .resize({ width: 500 })
    .webp({ quality: 80 })
    .toFile("optimized-500.webp")
);

const res = await fetch("https://www.example.com/some-file.jpg")
Readable.fromWeb(res.body).pipe(sharpStream);
await Promise.all(promises);

Src Content Docs Api Input (`docs/src/content/docs/api-input.md`) Copy Section

This file was auto-generated from JSDoc in lib/input.js

title: Input metadata Copy Chapter

metadata Copy Chapter

metadata([callback]) ⇒ Promise.<Object> | Sharp

Fast access to (uncached) image metadata without decoding any compressed pixel data.

This is read from the header of the input image.
It does not take into consideration any operations to be applied to the output image,
such as resize or rotate.

Dimensions in the response will respect the page and pages properties of the
constructor parameters.

A Promise is returned when callback is not provided.

• format: Name of decoder used to parse image e.g. jpeg, png, webp, gif, svg, heif, tiff
• mediaType: Media Type (MIME Type) e.g. image/jpeg, image/png, image/svg+xml, image/avif
• size: Total size of image in bytes, for Stream and Buffer input only
• width: Number of pixels wide (EXIF orientation is not taken into consideration, see example below)
• height: Number of pixels high (EXIF orientation is not taken into consideration, see example below)
• space: Name of colour space interpretation e.g. srgb, rgb, cmyk, lab, b-w ...
• channels: Number of bands e.g. 3 for sRGB, 4 for CMYK
• depth: Name of pixel depth format e.g. uchar, char, ushort, float ...
• density: Number of pixels per inch (DPI), if present
• chromaSubsampling: String containing JPEG chroma subsampling, 4:2:0 or 4:4:4 for RGB, 4:2:0:4 or 4:4:4:4 for CMYK
• isProgressive: Boolean indicating whether the image is interlaced using a progressive scan
• isPalette: Boolean indicating whether the image is palette-based (GIF, PNG).
• bitsPerSample: Number of bits per sample for each channel (GIF, PNG, HEIF).
• pages: Number of pages/frames contained within the image, with support for TIFF, HEIF, PDF, animated GIF and animated WebP
• pageHeight: Number of pixels high each page in a multi-page image will be.
• loop: Number of times to loop an animated image, zero refers to a continuous loop.
• delay: Delay in ms between each page in an animated image, provided as an array of integers.
• pagePrimary: Number of the primary page in a HEIF image
• levels: Details of each level in a multi-level image provided as an array of objects, requires libvips compiled with support for OpenSlide
• subifds: Number of Sub Image File Directories in an OME-TIFF image
• background: Default background colour, if present, for PNG (bKGD) and GIF images
• compression: The encoder used to compress an HEIF file, av1 (AVIF) or hevc (HEIC)
• resolutionUnit: The unit of resolution (density), either inch or cm, if present
• hasProfile: Boolean indicating the presence of an embedded ICC profile
• hasAlpha: Boolean indicating the presence of an alpha transparency channel
• orientation: Number value of the EXIF Orientation header, if present
• exif: Buffer containing raw EXIF data, if present
• icc: Buffer containing raw ICC profile data, if present
• iptc: Buffer containing raw IPTC data, if present
• xmp: Buffer containing raw XMP data, if present
• xmpAsString: String containing XMP data, if valid UTF-8.
• tifftagPhotoshop: Buffer containing raw TIFFTAG_PHOTOSHOP data, if present
• formatMagick: String containing format for images loaded via *magick
• comments: Array of keyword/text pairs representing PNG text blocks, if present.
• gainMap.image: HDR gain map, if present, as compressed JPEG image.

Example

const metadata = await sharp(input).metadata();

Example

const image = sharp(inputJpg);
image
  .metadata()
  .then(function(metadata) {
    return image
      .resize(Math.round(metadata.width / 2))
      .webp()
      .toBuffer();
  })
  .then(function(data) {
    // data contains a WebP image half the width and height of the original JPEG
  });

Example

// Get dimensions taking EXIF Orientation into account.
const { autoOrient } = await sharp(input).metadata();
const { width, height } = autoOrient;

stats Copy Chapter

stats([callback]) ⇒ Promise.<Object>

Access to pixel-derived image statistics for every channel in the image.
A Promise is returned when callback is not provided.

• channels: Array of channel statistics for each channel in the image. Each channel statistic contains
  • min (minimum value in the channel)
  • max (maximum value in the channel)
  • sum (sum of all values in a channel)
  • squaresSum (sum of squared values in a channel)
  • mean (mean of the values in a channel)
  • stdev (standard deviation for the values in a channel)
  • minX (x-coordinate of one of the pixel where the minimum lies)
  • minY (y-coordinate of one of the pixel where the minimum lies)
  • maxX (x-coordinate of one of the pixel where the maximum lies)
  • maxY (y-coordinate of one of the pixel where the maximum lies)
• isOpaque: Is the image fully opaque? Will be true if the image has no alpha channel or if every pixel is fully opaque.
• entropy: Histogram-based estimation of greyscale entropy, discarding alpha channel if any.
• sharpness: Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any.
• dominant: Object containing most dominant sRGB colour based on a 4096-bin 3D histogram.

Note: Statistics are derived from the original input image. Any operations performed on the image must first be
written to a buffer in order to run stats on the result (see third example).

Example

const image = sharp(inputJpg);
image
  .stats()
  .then(function(stats) {
     // stats contains the channel-wise statistics array and the isOpaque value
  });

Example

const { entropy, sharpness, dominant } = await sharp(input).stats();
const { r, g, b } = dominant;

Example

const image = sharp(input);
// store intermediate result
const part = await image.extract(region).toBuffer();
// create new instance to obtain statistics of extracted region
const stats = await sharp(part).stats();

Src Content Docs Api Operation (`docs/src/content/docs/api-operation.md`) Copy Section

This file was auto-generated from JSDoc in lib/operation.js

title: Image operations Copy Chapter

rotate Copy Chapter

rotate([angle], [options]) ⇒ Sharp

Rotate the output image.

The provided angle is converted to a valid positive degree rotation.
For example, -450 will produce a 270 degree rotation.

When rotating by an angle other than a multiple of 90,
the background colour can be provided with the background option.

For backwards compatibility, if no angle is provided, .autoOrient() will be called.

Only one rotation can occur per pipeline (aside from an initial call without
arguments to orient via EXIF data). Previous calls to rotate in the same
pipeline will be ignored.

Multi-page images can only be rotated by 180 degrees.

Method order is important when rotating, resizing and/or extracting regions,
for example .rotate(x).extract(y) will produce a different result to .extract(y).rotate(x).

Throws:

• Error Invalid parameters

Example

const rotateThenResize = await sharp(input)
  .rotate(90)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .toBuffer();
const resizeThenRotate = await sharp(input)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .rotate(90)
  .toBuffer();

autoOrient Copy Chapter

autoOrient() ⇒ Sharp

Auto-orient based on the EXIF Orientation tag, then remove the tag.
Mirroring is supported and may infer the use of a flip operation.

Only the EXIF Orientation tag is considered; orientation carried in other
places, such as an XMP tiff:Orientation element, is left untouched and
remains the responsibility of the consumer.

Previous or subsequent use of rotate(angle) and either flip() or flop()
will logically occur after auto-orientation, regardless of call order.

Example

const output = await sharp(input).autoOrient().toBuffer();

Example

const pipeline = sharp()
  .autoOrient()
  .resize(null, 200)
  .toBuffer(function (err, outputBuffer, info) {
    // outputBuffer contains 200px high JPEG image data,
    // auto-oriented using EXIF Orientation tag
    // info.width and info.height contain the dimensions of the resized image
  });
readableStream.pipe(pipeline);

flip Copy Chapter

flip([flip]) ⇒ Sharp

Mirror the image vertically (up-down) about the x-axis.
This always occurs before rotation, if any.

This operation does not work correctly with multi-page images.

Example

const output = await sharp(input).flip().toBuffer();

flop Copy Chapter

flop([flop]) ⇒ Sharp

Mirror the image horizontally (left-right) about the y-axis.
This always occurs before rotation, if any.

Example

const output = await sharp(input).flop().toBuffer();

affine Copy Chapter

affine(matrix, [options]) ⇒ Sharp

Perform an affine transform on an image. This operation will always occur after resizing, extraction and rotation, if any.

You must provide an array of length 4 or a 2x2 affine transformation matrix.
By default, new pixels are filled with a black background. You can provide a background colour with the background option.
A particular interpolator may also be specified. Set the interpolator option to an attribute of the sharp.interpolators Object e.g. sharp.interpolators.nohalo.

In the case of a 2x2 matrix, the transform is:

• X = matrix[0, 0] * (x + idx) + matrix[0, 1] * (y + idy) + odx
• Y = matrix[1, 0] * (x + idx) + matrix[1, 1] * (y + idy) + ody

where:

• x and y are the coordinates in input image.
• X and Y are the coordinates in output image.
• (0,0) is the upper left corner.

Throws:

• Error Invalid parameters

Since: 0.27.0

Example

const pipeline = sharp()
  .affine([[1, 0.3], [0.1, 0.7]], {
     background: 'white',
     interpolator: sharp.interpolators.nohalo
  })
  .toBuffer((err, outputBuffer, info) => {
     // outputBuffer contains the transformed image
     // info.width and info.height contain the new dimensions
  });

inputStream
  .pipe(pipeline);

sharpen Copy Chapter

sharpen([options]) ⇒ Sharp

Sharpen the image.

When used without parameters, performs a fast, mild sharpen of the output image.

When a sigma is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.

See libvips sharpen operation.

Throws:

• Error Invalid parameters

Example

const data = await sharp(input).sharpen().toBuffer();

Example

const data = await sharp(input).sharpen({ sigma: 2 }).toBuffer();

Example

const data = await sharp(input)
  .sharpen({
    sigma: 2,
    m1: 0,
    m2: 3,
    x1: 3,
    y2: 15,
    y3: 15,
  })
  .toBuffer();

median Copy Chapter

median([size]) ⇒ Sharp

Apply median filter.
When used without parameters the default window is 3x3.

Throws:

• Error Invalid parameters

Example

const output = await sharp(input).median().toBuffer();

Example

const output = await sharp(input).median(5).toBuffer();

blur Copy Chapter

blur([options]) ⇒ Sharp

Blur the image.

When used without parameters, performs a fast 3x3 box blur (equivalent to a box linear filter).

When a sigma is provided, performs a slower, more accurate Gaussian blur.

Throws:

• Error Invalid parameters

Example

const boxBlurred = await sharp(input)
  .blur()
  .toBuffer();

Example

const gaussianBlurred = await sharp(input)
  .blur(5)
  .toBuffer();

dilate Copy Chapter

dilate([width]) ⇒ Sharp

Expand foreground objects using the dilate morphological operator.

Throws:

• Error Invalid parameters

Example

const output = await sharp(input)
  .dilate()
  .toBuffer();

erode Copy Chapter

erode([width]) ⇒ Sharp

Shrink foreground objects using the erode morphological operator.

Throws:

• Error Invalid parameters

Example

const output = await sharp(input)
  .erode()
  .toBuffer();

flatten Copy Chapter

flatten([options]) ⇒ Sharp

Merge alpha transparency channel, if any, with a background, then remove the alpha channel.

See also removeAlpha.

Example

await sharp(rgbaInput)
  .flatten({ background: '#F0A703' })
  .toBuffer();

unflatten Copy Chapter

unflatten()

Ensure the image has an alpha channel
with all white pixel values made fully transparent.

Existing alpha channel values for non-white pixels remain unchanged.

Since: 0.32.1
Example

await sharp(rgbInput)
  .unflatten()
  .toBuffer();

Example

await sharp(rgbInput)
  .threshold(128, { grayscale: false }) // converter bright pixels to white
  .unflatten()
  .toBuffer();

gamma Copy Chapter

gamma([gamma], [gammaOut]) ⇒ Sharp

Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma
then increasing the encoding (brighten) post-resize at a factor of gamma.
This can improve the perceived brightness of a resized image in non-linear colour spaces.
JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation
when applying a gamma correction.

Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.

Throws:

• Error Invalid parameters

negate Copy Chapter

negate([options]) ⇒ Sharp

Produce the "negative" of the image.

Example

const output = await sharp(input)
  .negate()
  .toBuffer();

Example

const output = await sharp(input)
  .negate({ alpha: false })
  .toBuffer();

normalise Copy Chapter

normalise([options]) ⇒ Sharp

Enhance output image contrast by stretching its luminance to cover a full dynamic range.

Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.

Luminance values below the lower percentile will be underexposed by clipping to zero.
Luminance values above the upper percentile will be overexposed by clipping to the max pixel value.

Example

const output = await sharp(input)
  .normalise()
  .toBuffer();

Example

const output = await sharp(input)
  .normalise({ lower: 0, upper: 100 })
  .toBuffer();

normalize Copy Chapter

normalize([options]) ⇒ Sharp

Alternative spelling of normalise.

Example

const output = await sharp(input)
  .normalize()
  .toBuffer();

clahe Copy Chapter

clahe(options) ⇒ Sharp

Perform contrast limiting adaptive histogram equalization
CLAHE.

This will, in general, enhance the clarity of the image by bringing out darker details.

Throws:

• Error Invalid parameters

Since: 0.28.3

Example

const output = await sharp(input)
  .clahe({
    width: 3,
    height: 3,
  })
  .toBuffer();

convolve Copy Chapter

convolve(kernel) ⇒ Sharp

Convolve the image with the specified kernel.

Throws:

• Error Invalid parameters

Example

sharp(input)
  .convolve({
    width: 3,
    height: 3,
    kernel: [-1, 0, 1, -2, 0, 2, -1, 0, 1]
  })
  .raw()
  .toBuffer(function(err, data, info) {
    // data contains the raw pixel data representing the convolution
    // of the input image with the horizontal Sobel operator
  });

threshold Copy Chapter

threshold([threshold], [options]) ⇒ Sharp

Any pixel value greater than or equal to the threshold value will be set to 255, otherwise it will be set to 0.

Throws:

• Error Invalid parameters

boolean Copy Chapter

boolean(operand, operator, [options]) ⇒ Sharp

Perform a bitwise boolean operation with operand image.

This operation creates an output image where each pixel is the result of
the selected bitwise boolean operation between the corresponding pixels of the input images.

Throws:

• Error Invalid parameters

linear Copy Chapter

linear([a], [b]) ⇒ Sharp

Apply the linear formula a * input + b to the image to adjust image levels.

When a single number is provided, it will be used for all image channels.
When an array of numbers is provided, the array length must match the number of channels.

Throws:

• Error Invalid parameters

Example

await sharp(input)
  .linear(0.5, 2)
  .toBuffer();

Example

await sharp(rgbInput)
  .linear(
    [0.25, 0.5, 0.75],
    [150, 100, 50]
  )
  .toBuffer();

recomb Copy Chapter

recomb(inputMatrix) ⇒ Sharp

Recombine the image with the specified matrix.

Throws:

• Error Invalid parameters

Since: 0.21.1

Example

sharp(input)
  .recomb([
   [0.3588, 0.7044, 0.1368],
   [0.2990, 0.5870, 0.1140],
   [0.2392, 0.4696, 0.0912],
  ])
  .raw()
  .toBuffer(function(err, data, info) {
    // data contains the raw pixel data after applying the matrix
    // With this example input, a sepia filter has been applied
  });

modulate Copy Chapter

modulate([options]) ⇒ Sharp

Transforms the image using brightness, saturation, hue rotation, and lightness.
Brightness and lightness both operate on luminance, with the difference being that
brightness is multiplicative whereas lightness is additive.

Since: 0.22.1

Example

// increase brightness by a factor of 2
const output = await sharp(input)
  .modulate({
    brightness: 2
  })
  .toBuffer();

Example

// hue-rotate by 180 degrees
const output = await sharp(input)
  .modulate({
    hue: 180
  })
  .toBuffer();

Example

// increase lightness by +50
const output = await sharp(input)
  .modulate({
    lightness: 50
  })
  .toBuffer();

Example

// decrease brightness and saturation while also hue-rotating by 90 degrees
const output = await sharp(input)
  .modulate({
    brightness: 0.5,
    saturation: 0.5,
    hue: 90,
  })
  .toBuffer();

Src Content Docs Api Output (`docs/src/content/docs/api-output.md`) Copy Section

This file was auto-generated from JSDoc in lib/output.js

title: Output options Copy Chapter

toFile Copy Chapter

toFile(fileOut, [callback]) ⇒ Promise.<Object>

Write output image data to a file.

If an explicit output format is not selected, it will be inferred from the extension,
with JPEG, PNG, WebP, AVIF, TIFF, GIF, DZI, and libvips' V format supported.
Note that raw pixel data is only supported for buffer output.

By default all metadata will be removed, which includes EXIF-based orientation.
See withMetadata for control over this.

The caller is responsible for ensuring directory structures and permissions exist.

A Promise is returned when callback is not provided.

Returns: Promise.<Object> - - when no callback is provided
Throws:

• Error Invalid parameters

Example

sharp(input)
  .toFile('output.png', (err, info) => { ... });

Example

sharp(input)
  .toFile('output.png')
  .then(info => { ... })
  .catch(err => { ... });

toBuffer Copy Chapter

toBuffer([options], [callback]) ⇒ Promise.<Buffer>

Write output to a Buffer.
JPEG, PNG, WebP, AVIF, TIFF, GIF and raw pixel data output are supported.

Use toFormat or one of the format-specific functions such as jpeg, png etc. to set the output format.

If no explicit format is set, the output format will match the input image, except SVG input which becomes PNG output.

By default all metadata will be removed, which includes EXIF-based orientation.
See withMetadata for control over this.

callback, if present, gets three arguments (err, data, info) where:

• err is an error, if any.
• data is the output image data.
• info contains the output image format, size (bytes), width, height,
  channels and premultiplied (indicating if premultiplication was used).
  When using a crop strategy also contains cropOffsetLeft and cropOffsetTop.
  Animated output will also contain pageHeight and pages.
  May also contain textAutofitDpi (dpi the font was rendered at) if image was created from text.

The underlying ArrayBuffer may be marked as non-transferable by some JavaScript runtimes.
Use toUint8Array for a guaranteed transferable ArrayBuffer.

A Promise is returned when callback is not provided.

Returns: Promise.<Buffer> - - when no callback is provided

Example

const data = await sharp(input)
  .png()
  .toBuffer();

Example

const { data, info } = await sharp(input)
  .png()
  .toBuffer({ resolveWithObject: true });

Example

const { data, info } = await sharp('my-image.jpg')
  // output the raw pixels
  .raw()
  .toBuffer({ resolveWithObject: true });

// create a more type safe way to work with the raw pixel data
// this will not copy the data, instead it will change `data`s underlying ArrayBuffer
// so `data` and `pixelArray` point to the same memory location
const pixelArray = new Uint8ClampedArray(data.buffer);

// When you are done changing the pixelArray, sharp takes the `pixelArray` as an input
const { width, height, channels } = info;
await sharp(pixelArray, { raw: { width, height, channels } })
  .toFile('my-changed-image.jpg');

toUint8Array Copy Chapter

toUint8Array() ⇒ Promise.<{data: Uint8Array, info: Object}>

Write output to a Uint8Array backed by a transferable ArrayBuffer.
JPEG, PNG, WebP, AVIF, TIFF, GIF and raw pixel data output are supported.

Use toFormat or one of the format-specific functions such as jpeg, png etc. to set the output format.

If no explicit format is set, the output format will match the input image, except SVG input which becomes PNG output.

By default all metadata will be removed, which includes EXIF-based orientation.
See keepExif and similar methods for control over this.

Resolves with an Object containing:

• data is the output image as a Uint8Array backed by a transferable ArrayBuffer.
• info contains properties relating to the output image such as width and height.

Since: v0.35.0
Example

const { data, info } = await sharp(input).toUint8Array();

Example

const { data } = await sharp(input)
  .avif()
  .toUint8Array();
const base64String = data.toBase64();

withDensity Copy Chapter

withDensity(density) ⇒ Sharp

Set output density (DPI) in EXIF metadata.

Throws:

• Error Invalid parameters

Since: 0.35.0

Example

const data = await sharp(input)
  .withDensity(96)
  .toBuffer();

keepExif Copy Chapter

keepExif() ⇒ Sharp

Keep all EXIF metadata from the input image in the output image.

EXIF metadata is unsupported for TIFF output.

Since: 0.33.0
Example

const outputWithExif = await sharp(inputWithExif)
  .keepExif()
  .toBuffer();

withExif Copy Chapter

withExif(exif) ⇒ Sharp

Set EXIF metadata in the output image, ignoring any EXIF in the input image.

Throws:

• Error Invalid parameters

Since: 0.33.0

Example

const dataWithExif = await sharp(input)
  .withExif({
    IFD0: {
      Copyright: 'The National Gallery'
    },
    IFD3: {
      GPSLatitudeRef: 'N',
      GPSLatitude: '51/1 30/1 3230/100',
      GPSLongitudeRef: 'W',
      GPSLongitude: '0/1 7/1 4366/100'
    }
  })
  .toBuffer();

withExifMerge Copy Chapter

withExifMerge(exif) ⇒ Sharp

Update EXIF metadata from the input image in the output image.

Throws:

• Error Invalid parameters

Since: 0.33.0

Example

const dataWithMergedExif = await sharp(inputWithExif)
  .withExifMerge({
    IFD0: {
      Copyright: 'The National Gallery'
    }
  })
  .toBuffer();

keepIccProfile Copy Chapter

keepIccProfile() ⇒ Sharp

Keep ICC profile from the input image in the output image.

When input and output colour spaces differ, use with toColourspace and optionally pipelineColourspace.

Since: 0.33.0
Example

const outputWithIccProfile = await sharp(inputWithIccProfile)
  .keepIccProfile()
  .toBuffer();

Example

const cmykOutputWithIccProfile = await sharp(cmykInputWithIccProfile)
  .pipelineColourspace('cmyk')
  .toColourspace('cmyk')
  .keepIccProfile()
  .toBuffer();

withIccProfile Copy Chapter

withIccProfile(icc, [options]) ⇒ Sharp

Transform using an ICC profile and attach to the output image.

This can either be an absolute filesystem path or
built-in profile name (srgb, p3, cmyk).

Throws:

• Error Invalid parameters

Since: 0.33.0

Example

const outputWithP3 = await sharp(input)
  .withIccProfile('p3')
  .toBuffer();

keepGainMap Copy Chapter

keepGainMap() ⇒ Sharp

If the input contains gain map metadata, attempt to process the image and gain map separately,
recombining them into a single output image.

This approach is faster and should produce better results than withGainMap,
however not all operations are supported.

Only JPEG input and output are supported.
JPEG output options other than quality are ignored.

This feature is experimental and the API may change.

Since: 0.35.0
Example

const outputWithResizedGainMap = await sharp(inputWithGainMap)
  .keepGainMap()
  .resize({ width: 64 })
  .toBuffer();

withGainMap Copy Chapter

withGainMap() ⇒ Sharp

If the input contains gain map metadata, use it to convert the main image to HDR (High Dynamic Range) before further processing.
The input gain map is discarded.

If the output is JPEG, generate and attach a new ISO 21496-1 gain map.
JPEG output options other than quality are ignored.

This feature is experimental and the API may change.

Since: 0.35.0
Example

const outputWithRegeneratedGainMap = await sharp(inputWithGainMap)
  .withGainMap()
  .toBuffer();

keepXmp Copy Chapter

keepXmp() ⇒ Sharp

Keep XMP metadata from the input image in the output image.

Since: 0.34.3
Example

const outputWithXmp = await sharp(inputWithXmp)
  .keepXmp()
  .toBuffer();

withXmp Copy Chapter

withXmp(xmp) ⇒ Sharp

Set XMP metadata in the output image.

Supported by PNG, JPEG, WebP, and TIFF output.

Throws:

• Error Invalid parameters

Since: 0.34.3

Example

const xmpString = `
  <?xml version="1.0"?>
  <x:xmpmeta xmlns:x="adobe:ns:meta/">
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
        <dc:creator><rdf:Seq><rdf:li>John Doe</rdf:li></rdf:Seq></dc:creator>
      </rdf:Description>
    </rdf:RDF>
  </x:xmpmeta>`;

const data = await sharp(input)
  .withXmp(xmpString)
  .toBuffer();

keepMetadata Copy Chapter

keepMetadata() ⇒ Sharp

Keep all metadata (EXIF, ICC, XMP, IPTC) from the input image in the output image.

The default behaviour, when keepMetadata is not used, is to convert to the device-independent
sRGB colour space and strip all metadata, including the removal of any ICC profile.

Since: 0.33.0
Example

const outputWithMetadata = await sharp(inputWithMetadata)
  .keepMetadata()
  .toBuffer();

withMetadata Copy Chapter

withMetadata([options]) ⇒ Sharp

Keep most metadata (EXIF, XMP, IPTC) from the input image in the output image.

This will also convert to and add a web-friendly sRGB ICC profile if appropriate.

Allows orientation and density to be set or updated.

Throws:

• Error Invalid parameters

Example

const outputSrgbWithMetadata = await sharp(inputRgbWithMetadata)
  .withMetadata()
  .toBuffer();

Example

// Set output metadata to 96 DPI
const data = await sharp(input)
  .withMetadata({ density: 96 })
  .toBuffer();

toFormat Copy Chapter

toFormat(format, options) ⇒ Sharp

Force output to a given format.

Throws:

• Error unsupported format or options

Example

// Convert any input to PNG output
const data = await sharp(input)
  .toFormat('png')
  .toBuffer();

jpeg Copy Chapter

jpeg([options]) ⇒ Sharp

Use these JPEG options for output image.

Throws:

• Error Invalid options

Example

// Convert any input to very high quality JPEG output
const data = await sharp(input)
  .jpeg({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

Example

// Use mozjpeg to reduce output JPEG file size (slower)
const data = await sharp(input)
  .jpeg({ mozjpeg: true })
  .toBuffer();

png Copy Chapter

png([options]) ⇒ Sharp

Use these PNG options for output image.

By default, PNG output is full colour at 8 bits per pixel.

Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel.
Set palette to true for slower, indexed PNG output.

For 16 bits per pixel output, convert to rgb16 via
toColourspace.

Throws:

• Error Invalid options

Example

// Convert any input to full colour PNG output
const data = await sharp(input)
  .png()
  .toBuffer();

Example

// Convert any input to indexed PNG output (slower)
const data = await sharp(input)
  .png({ palette: true })
  .toBuffer();

Example

// Output 16 bits per pixel RGB(A)
const data = await sharp(input)
 .toColourspace('rgb16')
 .png()
 .toBuffer();

webp Copy Chapter

webp([options]) ⇒ Sharp

Use these WebP options for output image.

Throws:

• Error Invalid options

Example

// Convert any input to lossless WebP output
const data = await sharp(input)
  .webp({ lossless: true })
  .toBuffer();

Example

// Optimise the file size of an animated WebP
const outputWebp = await sharp(inputWebp, { animated: true })
  .webp({ effort: 6 })
  .toBuffer();

gif Copy Chapter

gif([options]) ⇒ Sharp

Use these GIF options for the output image.

The first entry in the palette is reserved for transparency.

The palette of the input image will be re-used if possible.

Throws:

• Error Invalid options

Since: 0.30.0

Example

// Convert PNG to GIF
await sharp(pngBuffer)
  .gif()
  .toBuffer();

Example

// Convert animated WebP to animated GIF
await sharp('animated.webp', { animated: true })
  .toFile('animated.gif');

Example

// Create a 128x128, cropped, non-dithered, animated thumbnail of an animated GIF
const out = await sharp('in.gif', { animated: true })
  .resize({ width: 128, height: 128 })
  .gif({ dither: 0 })
  .toBuffer();

Example

// Lossy file size reduction of animated GIF
await sharp('in.gif', { animated: true })
  .gif({ interFrameMaxError: 8 })
  .toFile('optim.gif');

jp2 Copy Chapter

jp2([options]) ⇒ Sharp

Use these JP2 options for output image.

Requires libvips compiled with support for OpenJPEG.
The prebuilt binaries do not include this - see
installing a custom libvips.

Throws:

• Error Invalid options

Since: 0.29.1

Example

// Convert any input to lossless JP2 output
const data = await sharp(input)
  .jp2({ lossless: true })
  .toBuffer();

Example

// Convert any input to very high quality JP2 output
const data = await sharp(input)
  .jp2({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

tiff Copy Chapter

tiff([options]) ⇒ Sharp

Use these TIFF options for output image.

The density can be set in pixels/inch via withMetadata
instead of providing xres and yres in pixels/mm.

Throws:

• Error Invalid options

Example

// Convert SVG input to LZW-compressed, 1 bit per pixel TIFF output
sharp('input.svg')
  .tiff({
    compression: 'lzw',
    bitdepth: 1
  })
  .toFile('1-bpp-output.tiff')
  .then(info => { ... });

avif Copy Chapter

avif([options]) ⇒ Sharp

Use these AVIF options for output image.

AVIF image sequences are not supported.

Throws:

• Error Invalid options

Since: 0.27.0

Example

const data = await sharp(input)
  .avif({ effort: 2 })
  .toBuffer();

Example

const data = await sharp(input)
  .avif({ lossless: true })
  .toBuffer();

heif Copy Chapter

heif(options) ⇒ Sharp

Use these HEIF options for output image.

Support for patent-encumbered HEIC images using hevc compression requires the use of a
globally-installed libvips compiled with support for libheif, libde265 and x265.

Throws:

• Error Invalid options

Since: 0.23.0

Example

const data = await sharp(input)
  .heif({ compression: 'hevc' })
  .toBuffer();

jxl Copy Chapter

jxl([options]) ⇒ Sharp

Use these JPEG-XL (JXL) options for output image.

This feature is experimental, please do not use in production systems.

Requires libvips compiled with support for libjxl.
The prebuilt binaries do not include this - see
installing a custom libvips.

Throws:

• Error Invalid options

Since: 0.31.3

raw Copy Chapter

raw([options]) ⇒ Sharp

Force output to be raw, uncompressed pixel data.
Pixel ordering is left-to-right, top-to-bottom, without padding.
Channel ordering will be RGB or RGBA for non-greyscale colourspaces.

Throws:

• Error Invalid options

Example

// Extract raw, unsigned 8-bit RGB pixel data from JPEG input
const { data, info } = await sharp('input.jpg')
  .raw()
  .toBuffer({ resolveWithObject: true });

Example

// Extract alpha channel as raw, unsigned 16-bit pixel data from PNG input
const data = await sharp('input.png')
  .ensureAlpha()
  .extractChannel(3)
  .toColourspace('b-w')
  .raw({ depth: 'ushort' })
  .toBuffer();

tile Copy Chapter

tile([options]) ⇒ Sharp

Use tile-based deep zoom (image pyramid) output.

Set the format and options for tile images via the toFormat, jpeg, png or webp functions.
Use a .zip or .szi file extension with toFile to write to a compressed archive file format.

The container will be set to zip when the output is a Buffer or Stream, otherwise it will default to fs.

Throws:

• Error Invalid parameters

Example

sharp('input.tiff')
  .png()
  .tile({
    size: 512
  })
  .toFile('output.dz', function(err, info) {
    // output.dzi is the Deep Zoom XML definition
    // output_files contains 512x512 tiles grouped by zoom level
  });

Example

const zipFileWithTiles = await sharp(input)
  .tile({ basename: "tiles" })
  .toBuffer();

Example

const iiififier = sharp().tile({ layout: "iiif" });
readableStream
  .pipe(iiififier)
  .pipe(writeableStream);

timeout Copy Chapter

timeout(options) ⇒ Sharp

Set a timeout for processing, in seconds.
Use a value of zero to continue processing indefinitely, the default behaviour.

The clock starts when libvips opens an input image for processing.
Time spent waiting for a libuv thread to become available is not included.

Since: 0.29.2

Example

// Ensure processing takes no longer than 3 seconds
try {
  const data = await sharp(input)
    .blur(1000)
    .timeout({ seconds: 3 })
    .toBuffer();
} catch (err) {
  if (err.message.includes('timeout')) { ... }
}

Src Content Docs Api Resize (`docs/src/content/docs/api-resize.md`) Copy Section

This file was auto-generated from JSDoc in lib/resize.js

title: Resizing images Copy Chapter

resize Copy Chapter

resize([width], [height], [options]) ⇒ Sharp

Resize image to width, height or width x height.

When both a width and height are provided, the possible methods by which the image should fit these are:

• cover: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
• contain: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
• fill: Ignore the aspect ratio of the input and stretch to both provided dimensions.
• inside: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
• outside: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.

Some of these values are based on the object-fit CSS property.

When using a fit of cover or contain, the default position is centre. Other options are:

• sharp.position: top, right top, right, right bottom, bottom, left bottom, left, left top.
• sharp.gravity: north, northeast, east, southeast, south, southwest, west, northwest, center or centre.
• sharp.strategy: cover only, dynamically crop using either the entropy or attention strategy.

Some of these values are based on the object-position CSS property.

The strategy-based approach initially resizes so one dimension is at its target length
then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.

• entropy: focus on the region with the highest Shannon entropy.
• attention: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.

Possible downsizing kernels are:

• nearest: Use nearest neighbour interpolation.
• linear: Use a triangle filter.
• cubic: Use a Catmull-Rom spline.
• mitchell: Use a Mitchell-Netravali spline.
• lanczos2: Use a Lanczos kernel with a=2.
• lanczos3: Use a Lanczos kernel with a=3 (the default).
• mks2013: Use a Magic Kernel Sharp 2013 kernel, as adopted by Facebook.
• mks2021: Use a Magic Kernel Sharp 2021 kernel, with more accurate (reduced) sharpening than the 2013 version.

When upsampling, these kernels map to nearest, linear and cubic interpolators.
Downsampling kernels without a matching upsampling interpolator map to cubic.

Only one resize can occur per pipeline.
Previous calls to resize in the same pipeline will be ignored.

Throws:

• Error Invalid parameters

Example

sharp(input)
  .resize({ width: 100 })
  .toBuffer()
  .then(data => {
    // 100 pixels wide, auto-scaled height
  });

Example

sharp(input)
  .resize({ height: 100 })
  .toBuffer()
  .then(data => {
    // 100 pixels high, auto-scaled width
  });

Example

sharp(input)
  .resize(200, 300, {
    kernel: sharp.kernel.nearest,
    fit: 'contain',
    position: 'right top',
    background: { r: 255, g: 255, b: 255, alpha: 0.5 }
  })
  .toFile('output.png')
  .then(() => {
    // output.png is a 200 pixels wide and 300 pixels high image
    // containing a nearest-neighbour scaled version
    // contained within the north-east corner of a semi-transparent white canvas
  });

Example

const transformer = sharp()
  .resize({
    width: 200,
    height: 200,
    fit: sharp.fit.cover,
    position: sharp.strategy.entropy
  });
// Read image data from readableStream
// Write 200px square auto-cropped image data to writableStream
readableStream
  .pipe(transformer)
  .pipe(writableStream);

Example

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.inside,
    withoutEnlargement: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains JPEG image data
    // no wider and no higher than 200 pixels
    // and no larger than the input image
  });

Example

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.outside,
    withoutReduction: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains JPEG image data
    // of at least 200 pixels wide and 200 pixels high while maintaining aspect ratio
    // and no smaller than the input image
  });

Example

const scaleByHalf = await sharp(input)
  .metadata()
  .then(({ width }) => sharp(input)
    .resize(Math.round(width * 0.5))
    .toBuffer()
  );

extend Copy Chapter

extend(extend) ⇒ Sharp

Extend / pad / extrude one or more edges of the image with either
the provided background colour or pixels derived from the image.
This operation will always occur after resizing and extraction, if any.

Throws:

• Error Invalid parameters

Example

// Resize to 140 pixels wide, then add 10 transparent pixels
// to the top, left and right edges and 20 to the bottom edge
sharp(input)
  .resize(140)
  .extend({
    top: 10,
    bottom: 20,
    left: 10,
    right: 10,
    background: { r: 0, g: 0, b: 0, alpha: 0 }
  })
  ...

Example

// Add a row of 10 red pixels to the bottom
sharp(input)
  .extend({
    bottom: 10,
    background: 'red'
  })
  ...

Example

// Extrude image by 8 pixels to the right, mirroring existing right hand edge
sharp(input)
  .extend({
    right: 8,
    background: 'mirror'
  })
  ...

extract Copy Chapter

extract(options) ⇒ Sharp

Extract/crop a region of the image.

• Use extract before resize for pre-resize extraction.
• Use extract after resize for post-resize extraction.
• Use extract twice and resize once for extract-then-resize-then-extract in a fixed operation order.

Throws:

• Error Invalid parameters

Example

sharp(input)
  .extract({ left: left, top: top, width: width, height: height })
  .toFile(output, function(err) {
    // Extract a region of the input image, saving in the same format.
  });

Example

sharp(input)
  .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
  .resize(width, height)
  .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
  .toFile(output, function(err) {
    // Extract a region, resize, then extract from the resized image
  });

trim Copy Chapter

trim([options]) ⇒ Sharp

Trim pixels from all edges that contain values similar to the given background colour, which defaults to that of the top-left pixel.

Images with an alpha channel will use the combined bounding box of alpha and non-alpha channels.

If the result of this operation would trim an image to nothing then no change is made.

Use the lineArt and threshold options for control over sensitivity.

The info response Object will contain trimOffsetLeft and trimOffsetTop properties.

Throws:

• Error Invalid parameters

Example

// Trim pixels with a colour similar to that of the top-left pixel.
await sharp(input)
  .trim()
  .toFile(output);

Example

// Trim pixels with the exact same colour as that of the top-left pixel.
await sharp(input)
  .trim({
    threshold: 0
  })
  .toFile(output);

Example

// Assume input is line art and trim only pixels with a similar colour to red.
const output = await sharp(input)
  .trim({
    background: "#FF0000",
    lineArt: true
  })
  .toBuffer();

Example

// Trim all "yellow-ish" pixels, being more lenient with the higher threshold.
const output = await sharp(input)
  .trim({
    background: "yellow",
    threshold: 42,
  })
  .toBuffer();

Example

// Trim image leaving (up to) a 10 pixel margin around the trimmed content.
const output = await sharp(input)
  .trim({
    margin: 10
  })
  .toBuffer();

Src Content Docs Api Utility (`docs/src/content/docs/api-utility.md`) Copy Section

This file was auto-generated from JSDoc in lib/utility.js

title: Global properties Copy Chapter

versions Copy Chapter

versions

An Object containing the version numbers of sharp, libvips
and (when using prebuilt binaries) its dependencies.

Example

console.log(sharp.versions);

interpolators Copy Chapter

interpolators : enum

An Object containing the available interpolators and their proper values

Read only: true
Properties

format Copy Chapter

format ⇒ Object

An Object containing nested boolean values representing the available input and output formats/methods.

Example

console.log(sharp.format);

queue Copy Chapter

queue

An EventEmitter that emits a change event when a task is either:

• queued, waiting for libuv to provide a worker thread
• complete

Example

sharp.queue.on('change', function(queueLength) {
  console.log('Queue contains ' + queueLength + ' task(s)');
});

cache Copy Chapter

cache([options]) ⇒ Object

Gets or, when options are provided, sets the limits of libvips' operation cache.
Existing entries in the cache will be trimmed after any change in limits.
This method always returns cache statistics,
useful for determining how much working memory is required for a particular task.

Example

const stats = sharp.cache();

Example

sharp.cache( { items: 200 } );
sharp.cache( { files: 0 } );
sharp.cache(false);

concurrency Copy Chapter

concurrency([concurrency]) ⇒ number

Gets or, when a concurrency is provided, sets
the maximum number of threads libvips should use to process each image.
These are from a thread pool managed by glib,
which helps avoid the overhead of creating new threads.

This method always returns the current concurrency.

The default value is the number of CPU cores,
except when using glibc-based Linux without jemalloc,
where the default is 1 to help reduce memory fragmentation.

A value of 0 will reset this to the number of CPU cores.

Some image format libraries spawn additional threads,
e.g. libaom manages its own 4 threads when encoding AVIF images,
and these are independent of the value set here.

:::note
Further control over performance is available.
:::

Returns: number - concurrency

Example

const threads = sharp.concurrency(); // 4
sharp.concurrency(2); // 2
sharp.concurrency(0); // 4

counters Copy Chapter

counters() ⇒ Object

Provides access to internal task counters.

• queue is the number of tasks this module has queued waiting for libuv to provide a worker thread from its pool.
• process is the number of resize tasks currently being processed.

Example

const counters = sharp.counters(); // { queue: 2, process: 4 }

simd Copy Chapter

simd([simd]) ⇒ boolean

Get and set use of SIMD vector unit instructions.
Requires libvips to have been compiled with highway support.

Improves the performance of resize, blur and sharpen operations
by taking advantage of the SIMD vector unit of the CPU, e.g. Intel SSE and ARM NEON.

Example

const simd = sharp.simd();
// simd is `true` if the runtime use of highway is currently enabled

Example

const simd = sharp.simd(false);
// prevent libvips from using highway at runtime

block Copy Chapter

block(options)

Block libvips operations at runtime.

This is in addition to the VIPS_BLOCK_UNTRUSTED environment variable,
which when set will block all "untrusted" operations.

Since: 0.32.4

Example (Block all TIFF input.)

sharp.block({
  operation: ['VipsForeignLoadTiff']
});

unblock Copy Chapter

unblock(options)

Unblock libvips operations at runtime.

This is useful for defining a list of allowed operations.

Since: 0.32.4

Example (Block all input except WebP from the filesystem.)

sharp.block({
  operation: ['VipsForeignLoad']
});
sharp.unblock({
  operation: ['VipsForeignLoadWebpFile']
});

Example (Block all input except JPEG and PNG from a Buffer or Stream.)

sharp.block({
  operation: ['VipsForeignLoad']
});
sharp.unblock({
  operation: ['VipsForeignLoadJpegBuffer', 'VipsForeignLoadPngBuffer']
});

Src Content Docs Install (`docs/src/content/docs/install.md`) Copy Section

title: Installation Copy Chapter

Works with your choice of JavaScript package manager.

:::caution
Please ensure your package manager is configured to install optional dependencies
:::

If a package manager lockfile must support multiple platforms,
please see the cross-platform section
to help decide which package manager is appropriate.

npm install sharp

pnpm add sharp

yarn add sharp

bun add sharp

deno add --quiet npm:sharp
deno run --allow-env --allow-ffi --allow-read --allow-sys ...

Prerequisites Copy Chapter

• Node-API v9 compatible runtime e.g. Node.js >= 20.9.0.

Prebuilt binaries Copy Chapter

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

• macOS x64 (>= 10.15)
• macOS ARM64
• Linux ARM (glibc >= 2.36)
• Linux ARM64 (glibc >= 2.28, musl >= 1.2.5)
• Linux RISC-V 64-bit (glibc >= 2.41)
• Linux ppc64 (glibc >= 2.36)
• Linux s390x (glibc >= 2.36)
• Linux x64 (glibc >= 2.28, musl >= 1.2.5, CPU with SSE4.2)
• Windows x64
• Windows x86 (deprecated, Node.js 20 only)
• Windows ARM64
• FreeBSD (WebAssembly)

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

Cross-platform Copy Chapter

At install time, package managers will automatically select prebuilt binaries
for the current OS platform and CPU architecture, where available.

Some package managers support multiple platforms and architectures
within the same installation tree and/or using the same lockfile.

npm v10+ Copy Section

:::caution
npm package-lock.json files shared by multiple platforms can cause installation problems due to npm bug #4828
:::

Provides limited support via --os, --cpu and --libc flags.

To support macOS with Intel x64 and ARM64 CPUs:

npm install --cpu=x64 --os=darwin sharp
npm install --cpu=arm64 --os=darwin sharp

When the cross-target is Linux, the C standard library must be specified.

To support glibc (e.g. Debian) and musl (e.g. Alpine) Linux with Intel x64 CPUs:

npm install --cpu=x64 --os=linux --libc=glibc sharp
npm install --cpu=x64 --os=linux --libc=musl sharp

yarn v3+ Copy Section

Use the supportedArchitectures configuration.

pnpm v8+ Copy Section

Use the supportedArchitectures configuration.

Custom libvips Copy Chapter

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 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 Copy Chapter

npm install sharp
npm explore sharp -- npm run build

The build process will search for a globally-installed libvips.
This detection logic can be skipped by setting the
SHARP_IGNORE_GLOBAL_LIBVIPS (never try to use it) or
SHARP_FORCE_GLOBAL_LIBVIPS (always try to use it, even when missing or outdated)
environment variables.

Building from source requires:

• C++17 compiler
• node-addon-api version 7+
• node-gyp version 9+ and its dependencies

If node-addon-api or node-gyp cannot be found, try adding them via:

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

WebAssembly Copy Chapter

Runtime environments that provide multi-threaded Wasm via Workers are supported
by the optional @img/sharp-wasm32 package.

npm install sharp @img/sharp-wasm32

• Use in web browsers is unsupported.
• Use in single-threaded environments is unsupported.
• Native text rendering is unsupported.
• Tile-based output is unsupported.

Linux memory allocator Copy Chapter

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 Copy Chapter

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,
see the cross-platform section to help decide which package manager is appropriate
and how to configure it.

Some package managers use symbolic links
but AWS Lambda does not support these within deployment packages.

An alternative approach is to use a well-maintained, third-party Lambda Layer:

• cbschuld/sharp-aws-lambda-layer
• pH200/sharp-layer
• zoellner/sharp-heic-lambda-layer

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 Copy Chapter

webpack Copy Section

Ensure sharp is excluded from bundling via the
externals
configuration.

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

esbuild Copy Section

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 --os=linux --libc=glibc --cpu=x64 sharp

electron Copy Section

electron-builder

Ensure sharp is unpacked from the ASAR archive file using the
asarUnpack
option.

{
  "build": {
    "asar": true,
    "asarUnpack": [
      "**/node_modules/sharp/**/*",
      "**/node_modules/@img/**/*"
    ]
  }
}

electron-forge

Ensure sharp is unpacked from the ASAR archive file using the
unpack
option.

{
  "packagerConfig": {
    "asar": {
      "unpack": "**/node_modules/{sharp,@img}/**/*"
    }
  }
}

When using electron-forge with Webpack,
you may also need to add
forge-externals-plugin.

vite Copy Section

Ensure sharp is excluded from bundling via the
build.rollupOptions
configuration.

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      external: [
        "sharp"
      ]
    }
  }
});

TypeScript Copy Chapter

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 Copy Chapter

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.

Known conflicts Copy Chapter

Canvas and Windows Copy Section

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.

Electron and Linux Copy Section

Binaries provided by Electron for use on Linux dynamically link against a globally-installed glib
and leak its symbols into the process space, which may cause the following error to occur:

GLib-GObject: g_object_ref: assertion 'G_IS_OBJECT (object)' failed
GLib-GObject: g_object_unref: assertion 'G_IS_OBJECT (object)' failed

Please subscribe to
electron#46323
for updates.

Src Content Docs Performance (`docs/src/content/docs/performance.md`) Copy Section

title: Performance Copy Chapter

Parallelism and concurrency Copy Chapter

Node.js uses a libuv-managed thread pool when processing asynchronous calls to native modules such as sharp.

The maximum number of images that sharp can process in parallel is controlled by libuv's
UV_THREADPOOL_SIZE
environment variable, which defaults to 4.

When using more than 4 physical CPU cores, set this environment variable
before the Node.js process starts to increase the thread pool size.

export UV_THREADPOOL_SIZE="$(lscpu -p | egrep -v "^#" | sort -u -t, -k 2,4 | wc -l)"

libvips uses a shared thread pool to avoid the overhead of spawning new threads.
The size of this thread pool will grow on demand and shrink when idle.

The default number of threads used to concurrently process each image is the same as the number of CPU cores,
except when using glibc-based Linux without jemalloc or without MALLOC_ARENA_MAX,
where the default is 1 to help reduce memory fragmentation.

Use sharp.concurrency() to manage the number of threads per image.

To reduce memory fragmentation when using the default Linux glibc memory allocator, set the
MALLOC_ARENA_MAX
environment variable to either 2 or 4 before the Node.js process starts to reduce the number of memory pools.

export MALLOC_ARENA_MAX="2"

Benchmark Copy Chapter

A test to benchmark the performance of this module relative to alternatives.

Greater libvips performance can be expected with caching enabled (default)
and using 8+ core machines, especially those with larger L1/L2 CPU caches.

The I/O limits of the relevant (de)compression library will generally determine maximum throughput.

Contenders Copy Section

• jimp v1.6.1 - Image processing in pure JavaScript.
• imagemagick v0.1.3 - Supports filesystem only and "has been unmaintained for a long time".
• gm v1.25.1 - Fully featured wrapper around GraphicsMagick's gm command line utility, but "has been sunset".
• sharp v0.35.0 / libvips v8.18.2 - Caching within libvips disabled to ensure a fair comparison.

Environment Copy Section

AMD64

• AWS EC2 us-west-2 c8a.xlarge (4x AMD EPYC 9R45)
• Ubuntu 25.10
• Node.js 24.15.0

ARM64

• AWS EC2 us-west-2 c8g.xlarge (4x ARM Graviton4)
• Ubuntu 25.10
• Node.js 24.15.0

Task: JPEG Copy Section

Decompress a 2725x2225 JPEG image,
resize to 720x588 using Lanczos 3 resampling (where available),
then compress to JPEG at a "quality" setting of 80.

Note: jimp does not support Lanczos 3, bicubic resampling used instead.

Results: JPEG (AMD64)

Results: JPEG (ARM64)

Task: PNG Copy Section

Decompress a 2048x1536 RGBA PNG image,
premultiply the alpha channel,
resize to 720x540 using Lanczos 3 resampling (where available),
unpremultiply then compress as PNG with a "default" zlib compression level of 6
and without adaptive filtering.

Note: jimp does not support premultiply/unpremultiply.

Results: PNG (AMD64)

Results: PNG (ARM64)

Running the benchmark test Copy Chapter

Requires Docker.

git clone https://github.com/lovell/sharp.git
cd sharp/test/bench
./run-with-docker.sh

Src Content Docs Changelog V0.10.0 (`docs/src/content/docs/changelog/v0.10.0.md`) Copy Section

title: v0.10.0 - 23rd April 2015 slug: changelog/v0.10.0 Copy Chapter

• Add support for Windows (x86).
  #19
  @DullReferenceException
  @itsananderson

• Add support for Openslide input and DeepZoom output.
  #146
  @mvictoras

• Allow arbitrary aspect ratios when resizing images via new ignoreAspectRatio method.
  #192
  @skedastik

• Enhance output image contrast by stretching its luminance to cover the full dynamic range via new normalize method.
  #194
  @bkw
  @codingforce

Src Content Docs Changelog V0.10.1 (`docs/src/content/docs/changelog/v0.10.1.md`) Copy Section

title: v0.10.1 - 1st June 2015 slug: changelog/v0.10.1 Copy Chapter

• Allow embed of image with alpha transparency onto non-transparent background.
  #204
  @mikemliu

• Include C standard library for atoi as Xcode 6.3 appears to no longer do this.
  #228
  @doggan

Src Content Docs Changelog V0.11.0 (`docs/src/content/docs/changelog/v0.11.0.md`) Copy Section

title: v0.11.0 - 15th July 2015 slug: changelog/v0.11.0 Copy Chapter

• Allow alpha transparency compositing via new overlayWith method.
  #97
  @gasi

• Expose raw ICC profile data as a Buffer when using metadata.
  #129
  @homerjam

• Allow image header updates via a parameter passed to existing withMetadata method.
  Provide initial support for EXIF Orientation tag,
  which if present is now removed when using rotate, flip or flop.
  #189
  @h2non

• Tighten constructor parameter checks.
  #221
  @mikemorris

• Allow one input Stream to be shared with two or more output Streams via new clone method.
  #235
  @jaubourg

• Use round instead of floor when auto-scaling dimensions to avoid floating-point rounding errors.
  #238
  @richardadjogah

Src Content Docs Changelog V0.11.1 (`docs/src/content/docs/changelog/v0.11.1.md`) Copy Section

title: v0.11.1 - 12th August 2015 slug: changelog/v0.11.1 Copy Chapter

• Silence MSVC warning: "C4530: C++ exception handler used, but unwind semantics are not enabled".
  #244
  @TheThing

• Suppress gamma correction for input image with alpha transparency.
  #249
  @compeak

Src Content Docs Changelog V0.11.2 (`docs/src/content/docs/changelog/v0.11.2.md`) Copy Section

title: v0.11.2 - 28th August 2015 slug: changelog/v0.11.2 Copy Chapter

• Allow crop gravity to be provided as a String.
  #255
  @papandreou
• Add support for io.js v3 and Node v4.
  #246

Src Content Docs Changelog V0.11.3 (`docs/src/content/docs/changelog/v0.11.3.md`) Copy Section

title: v0.11.3 - 8th September 2015 slug: changelog/v0.11.3 Copy Chapter

• Interpret blurSigma, sharpenFlat, and sharpenJagged as double precision.
  #263
  @chrisriley

Src Content Docs Changelog V0.11.4 (`docs/src/content/docs/changelog/v0.11.4.md`) Copy Section

title: v0.11.4 - 5th November 2015 slug: changelog/v0.11.4 Copy Chapter

• Add corners, e.g. northeast, to existing gravity option.
  #291
  @brandonaaron

• Ensure correct auto-rotation for EXIF Orientation values 2 and 4.
  #288
  @brandonaaron

• Make static linking possible via --runtime_link install option.
  #287
  @vlapo

Src Content Docs Changelog V0.12.0 (`docs/src/content/docs/changelog/v0.12.0.md`) Copy Section

title: v0.12.0 - 23rd November 2015 slug: changelog/v0.12.0 Copy Chapter

• Bundle pre-compiled libvips and its dependencies for 64-bit Linux and Windows.
  #42

• Take advantage of libvips v8.1.0+ features.
  #152

• Add support for 64-bit Windows. Drop support for 32-bit Windows.
  #224
  @sabrehagen

• Switch default interpolator to bicubic.
  #289
  @mahnunchik

• Pre-extract rotation should not swap width/height.
  #296
  @asilvas

• Ensure 16-bit+alpha input images are (un)premultiplied correctly.
  #301
  @izaakschroeder

• Add threshold operation.
  #303
  @dacarley

• Add negate operation.
  #306
  @dacarley

• Support options Object with existing extract operation.
  #309
  @papandreou

Src Content Docs Changelog V0.12.1 (`docs/src/content/docs/changelog/v0.12.1.md`) Copy Section

title: v0.12.1 - 12th December 2015 slug: changelog/v0.12.1 Copy Chapter

• Allow use of SIMD vector instructions (via liborc) to be toggled on/off.
  #172
  @bkw
  @puzrin

• Ensure embedded ICC profiles output with perceptual intent.
  #321
  @vlapo

• Use the NPM-configured HTTPS proxy, if any, for binary downloads.

Src Content Docs Changelog V0.12.2 (`docs/src/content/docs/changelog/v0.12.2.md`) Copy Section

title: v0.12.2 - 16th January 2016 slug: changelog/v0.12.2 Copy Chapter

• Upgrade libvips to v8.2.0 for improved vips_shrink.

• Add pre-compiled libvips for ARMv6+ CPUs.

• Ensure 16-bit input images work with embed option.
  #325
  @janaz

• Allow compilation with gmake to provide FreeBSD support.
  #326
  @c0decafe

• Attempt to remove temporary file after installation.
  #331
  @dtoubelis

Src Content Docs Changelog V0.13.0 (`docs/src/content/docs/changelog/v0.13.0.md`) Copy Section

title: v0.13.0 - 15th February 2016 slug: changelog/v0.13.0 Copy Chapter

• Improve vector image support by allowing control of density/DPI.
  Switch pre-built libs from Imagemagick to Graphicsmagick.
  #110
  @bradisbell

• Add support for raw, uncompressed pixel Buffer/Stream input.
  #220
  @mikemorris

• Switch from libvips' C to C++ bindings, requires upgrade to v8.2.2.
  #299

• Control number of open files in libvips' cache; breaks existing cache behaviour.
  #315
  @impomezia

• Ensure 16-bit input images can be normalised and embedded onto transparent backgrounds.
  #339
  #340
  @janaz

• Ensure selected format takes precedence over any unknown output filename extension.
  #344
  @ubaltaci

• Add support for libvips' PBM, PGM, PPM and FITS image format loaders.
  #347
  @oaleynik

• Ensure default crop gravity is center/centre.
  #351
  @joelmukuthu

• Improve support for musl libc systems e.g. Alpine Linux.
  #354
  #359
  @download13
  @wjordan

• Small optimisation when reducing by an integral factor to favour shrink over affine.

• Add support for gamma correction of images with an alpha channel.

Src Content Docs Changelog V0.13.1 (`docs/src/content/docs/changelog/v0.13.1.md`) Copy Section

title: v0.13.1 - 27th February 2016 slug: changelog/v0.13.1 Copy Chapter

• Fix embedding onto transparent backgrounds; regression introduced in v0.13.0.
  #366
  @diegocsandrim

Src Content Docs Changelog V0.14.0 (`docs/src/content/docs/changelog/v0.14.0.md`) Copy Section

title: v0.14.0 - 2nd April 2016 slug: changelog/v0.14.0 Copy Chapter

• Add ability to extend (pad) the edges of an image.
  #128
  @blowsie

• Add support for Zoomify and Google tile layouts. Breaks existing tile API.
  #223
  @bdunnette

• Improvements to overlayWith: differing sizes/formats, gravity, buffer input.
  #239
  @chrisriley

• Add entropy-based crop strategy to remove least interesting edges.
  #295
  @rightaway

• Expose density metadata; set density of images from vector input.
  #338
  @lookfirst

• Emit post-processing 'info' event for Stream output.
  #367
  @salzhrani

• Ensure output image EXIF Orientation values are within 1-8 range.
  #385
  @jtobinisaniceguy

• Ensure ratios are not swapped when rotating 90/270 and ignoring aspect.
  #387
  @kleisauke

• Remove deprecated style of calling extract API. Breaks calls using positional arguments.
  #276

Src Content Docs Changelog V0.14.1 (`docs/src/content/docs/changelog/v0.14.1.md`) Copy Section

title: v0.14.1 - 16th April 2016 slug: changelog/v0.14.1 Copy Chapter

• Allow removal of limitation on input pixel count via limitInputPixels. Use with care.
  #250
  #316
  @anandthakker
  @kentongray

• Use final output image for metadata passed to callback.
  #399
  @salzhrani

• Add support for writing tiled images to a zip container.
  #402
  @felixbuenemann

• Allow use of embed with 1 and 2 channel images.
  #411
  @janaz

• Improve Electron compatibility by allowing node-gyp rebuilds without npm.
  #412
  @nouh

Src Content Docs Changelog V0.15.0 (`docs/src/content/docs/changelog/v0.15.0.md`) Copy Section

title: v0.15.0 - 21st May 2016 slug: changelog/v0.15.0 Copy Chapter

• Use libvips' new Lanczos 3 kernel as default for image reduction.
  Deprecate interpolateWith method, now provided as a resize option.
  #310
  @jcupitt

• Take advantage of libvips v8.3 features.
  Add support for libvips' new GIF and SVG loaders.
  Pre-built binaries now include giflib and librsvg, exclude *magick.
  Use shrink-on-load for WebP input.
  Break existing sharpen API to accept sigma and improve precision.
  #369

• Remove unnecessary (un)premultiply operations when not resizing/compositing.
  #413
  @jardakotesovec

Src Content Docs Changelog V0.15.1 (`docs/src/content/docs/changelog/v0.15.1.md`) Copy Section

title: v0.15.1 - 12th July 2016 slug: changelog/v0.15.1 Copy Chapter

• Concat Stream-based input in single operation for ~+3% perf and less GC.
  #429
  @papandreou

• Add alpha channel, if required, before extend operation.
  #439
  @frulo

• Allow overlay image to be repeated across entire image via tile option.
  #443
  @lemnisk8

• Add cutout option to overlayWith feature, applies only the alpha channel of the overlay image.
  #448
  @kleisauke

• Ensure scaling factors are calculated independently to prevent rounding errors.
  #452
  @puzrin

• Add --sharp-cxx11 flag to compile with gcc's new C++11 ABI.
  #456
  @kapouer

• Add top/left offset support to overlayWith operation.
  #473
  @rnanwani

• Add convolve operation for kernel-based convolution.
  #479
  @mhirsch

• Add greyscale option to threshold operation for colourspace conversion control.
  #480
  @mhirsch

• Ensure ICC profiles are licenced for distribution.
  #486
  @kapouer

• Allow images with an alpha channel to work with LAB-colourspace based sharpen.
  #490
  @jwagner

• Add trim operation to remove "boring" edges.
  #492
  @kleisauke

• Add bandbool feature for channel-wise boolean operations.
  #496
  @mhirsch

• Add extractChannel operation to extract a channel from an image.
  #497
  @mhirsch

• Add ability to read and write native libvips .v files.
  #500
  @mhirsch

• Add boolean feature for bitwise image operations.
  #501
  @mhirsch

Src Content Docs Changelog V0.16.0 (`docs/src/content/docs/changelog/v0.16.0.md`) Copy Section

title: v0.16.0 - 18th August 2016 slug: changelog/v0.16.0 Copy Chapter