{"id":10421,"library":"sharp","title":"Sharp: High-Performance Image Processor","description":"Sharp is a high-performance Node.js module designed for fast image processing, offering extensive support for resizing, converting, and manipulating JPEG, PNG, WebP, AVIF, GIF, TIFF, and SVG images. It leverages the native libvips library, making it one of the fastest solutions available for image operations in Node.js environments. The current stable version is 0.34.5, with frequent updates including patch releases and release candidates for upcoming major versions like 0.35.0. It's differentiated by its speed, low memory footprint, and broad format compatibility, making it suitable for high-volume image processing tasks such as thumbnail generation and on-the-fly image transformations for web applications. The project actively maintains support for recent Node.js LTS versions and ships with TypeScript types.","status":"active","version":"0.34.5","language":"javascript","source_language":"en","source_url":"git://github.com/lovell/sharp","tags":["javascript","jpeg","png","webp","avif","tiff","gif","svg","jp2","typescript"],"install":[{"cmd":"npm install sharp","lang":"bash","label":"npm"},{"cmd":"yarn add sharp","lang":"bash","label":"yarn"},{"cmd":"pnpm add sharp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary entry point is the default export, which is a function that can be called directly with a buffer or file path.","wrong":"const sharp = require('sharp');","symbol":"sharp","correct":"import sharp from 'sharp';"},{"note":"The `Sharp` type is useful for type hinting when chaining operations on an image instance.","symbol":"Sharp","correct":"import sharp, { type Sharp } from 'sharp';"},{"note":"Type imports like `FormatEnum` are used for strictly typing format options and are often omitted in plain JavaScript.","symbol":"FormatEnum","correct":"import type { FormatEnum } from 'sharp';"}],"quickstart":{"code":"import sharp from 'sharp';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nconst inputImagePath = './input.jpg'; // Ensure this file exists for the example\nconst outputDirectory = './output';\n\nasync function processImage() {\n  try {\n    await fs.mkdir(outputDirectory, { recursive: true });\n\n    // Create a dummy input file if it doesn't exist for the example\n    try {\n      await fs.access(inputImagePath);\n    } catch (error) {\n      console.log('Creating a dummy input.jpg for the example...');\n      await sharp({ create: { width: 500, height: 300, channels: 3, background: { r: 255, g: 100, b: 50 } } })\n        .jpeg({ quality: 80 })\n        .toFile(inputImagePath);\n    }\n\n    const outputWebPPath = path.join(outputDirectory, 'output-resized.webp');\n    const outputJpgPath = path.join(outputDirectory, 'output-thumb.jpg');\n\n    console.log(`Processing ${inputImagePath}...`);\n\n    // Resize to 320x240 and convert to WebP\n    await sharp(inputImagePath)\n      .resize(320, 240, { fit: 'cover' })\n      .webp({ quality: 90 })\n      .toFile(outputWebPPath);\n    console.log(`Image resized and converted to WebP: ${outputWebPPath}`);\n\n    // Create a 150px square thumbnail, grayscale, and convert to JPEG\n    await sharp(inputImagePath)\n      .resize(150, 150, { fit: 'cover' })\n      .grayscale()\n      .jpeg({ quality: 75 })\n      .toFile(outputJpgPath);\n    console.log(`Image thumbnailed and converted to JPEG: ${outputJpgPath}`);\n\n  } catch (error) {\n    console.error('Error processing image:', error);\n  }\n}\n\nprocessImage();\n","lang":"typescript","description":"This quickstart demonstrates how to use sharp to resize an image, convert it to different formats (WebP and JPEG), and apply common transformations like grayscale, saving the results to files. It also handles creating a dummy input file if needed."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.9.0 or higher. For production environments, consider moving to the latest LTS release of Node.js.","message":"Sharp v0.35.0 (and its release candidates) drops support for Node.js 18. Users must upgrade to Node.js >= 20.9.0.","severity":"breaking","affected_versions":">=0.35.0-rc.0"},{"fix":"If you relied on `sharp` compiling from source during `npm install`, you will now need to explicitly run `npm run build` or `npm install --build-from-source` (pre-v0.34.5) if pre-built binaries are not suitable for your environment. Check the official documentation for the updated build process.","message":"Starting with v0.35.0, the `install` script has been removed from `package.json`. Compiling from source is now an opt-in process using the `build` script.","severity":"breaking","affected_versions":">=0.35.0-rc.0"},{"fix":"Review your code for usage of `failOnError`, `paletteBitDepth`, and the deprecated `sharpen` properties. Replace them with the recommended alternatives or remove them if no longer necessary. Consult the sharp changelog for specific replacements.","message":"The `failOnError` constructor property has been removed, as well as `paletteBitDepth` from the `metadata` response, and several properties from `sharpen`.","severity":"breaking","affected_versions":">=0.35.0-rc.0"},{"fix":"If installation fails, check the sharp installation guide for required system dependencies for your operating system. For `npm install --build-from-source` (deprecated in v0.34.5, replaced by `npm run build` in v0.35.0+), ensure you have `node-gyp` prerequisites installed (Python, C++ compiler).","message":"Sharp is a native Node.js module and requires `libvips` to be available. While it often ships with pre-compiled binaries, certain environments or specific `libvips` features might necessitate building from source, which can fail due to missing system dependencies (e.g., C++ compilers, development headers).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For extremely large images, consider processing them in chunks or using input streams to manage memory more effectively. Ensure you are streaming or writing to file as soon as possible, rather than keeping large buffers in memory across multiple operations. Monitor Node.js heap usage and consider increasing `--max-old-space-size` if necessary, though optimizing code is preferable.","message":"Memory usage can be a concern when processing very large images, especially with chained operations. While `sharp` is memory-efficient, unoptimized usage can still lead to 'JavaScript heap out of memory' errors in Node.js.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.34.5':62 '0.35.0':77 'activ':117 'applic':114 'avail':50 'avif':31,134 'broad':88 'candid':71 'compat':90 'convert':25 'current':58 'design':15 'differenti':80 'environ':56 'extens':21 'fast':17 'fastest':48 'fli':109 'footprint':86 'format':89 'frequent':64 'generat':104 'gif':32,136 'high':3,11,96 'high-perform':2,10 'high-volum':95 'imag':5,18,36,52,98,110 'includ':66 'javascript':130 'jp2':138 'jpeg':28,131 'leverag':38 'librari':42 'libvip':41 'like':76 'low':84 'lts':123 'maintain':118 'major':74 'make':43,91 'manipul':27 'memori':85 'modul':14 'nativ':40 'node.js':13,55,122 'offer':20 'on-the-fli':106 'one':45 'oper':53 'patch':67 'perform':4,12 'png':29,132 'process':19,99 'processor':6 'project':116 'recent':121 'releas':68,70 'resiz':24 'sharp':1,7 'ship':126 'solut':49 'speed':83 'stabl':59 'suitabl':93 'support':22,119 'svg':35,137 'task':100 'thumbnail':103 'tiff':33,135 'transform':111 'type':129 'typescript':128,139 'upcom':73 'updat':65 'version':60,75,124 'volum':97 'web':113 'webp':30,133","created_at":"2026-04-18T08:58:43.531182+00:00","updated_at":"2026-04-19T05:46:55.918492+00:00","problems":[{"fix":"Ensure the directory where you are trying to write the image exists and that the Node.js process has write permissions for it. You might need to change directory permissions (e.g., `chmod 777 /path/to/output`) or run your application with appropriate user privileges.","cause":"The Node.js process does not have sufficient write permissions to the specified output directory or file.","error":"Error: EACCES: permission denied, open 'path/to/output.jpg'"},{"fix":"Verify the input file's integrity and ensure its format is one of the supported types (JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG, JP2). Check for common issues like incorrect file extensions that don't match the actual file content.","cause":"Sharp was unable to identify or process the format of the input image file. This could be due to a corrupted file, an unrecognized extension, or a format not supported by the underlying libvips library.","error":"Error: Input file contains unsupported image format"},{"fix":"Run `npm install sharp` or `yarn add sharp`. If this persists, clear your npm cache (`npm cache clean --force`), delete `node_modules`, and `package-lock.json`, then reinstall. If it's a native module compilation issue, check system dependencies required for `libvips`.","cause":"The `sharp` package or its native bindings were not correctly installed or are not accessible in the current environment.","error":"Error: Cannot find module 'sharp'"},{"fix":"This often points to a problem with the `sharp` installation's native components. Try completely reinstalling `sharp` by deleting `node_modules` and `package-lock.json` (or `yarn.lock`) and running `npm install sharp`. If installing on a custom environment or Docker, ensure all `libvips` dependencies are correctly set up for your specific build.","cause":"This usually indicates an issue with the underlying `libvips` library installation or configuration, where a required image loader (e.g., JPEG loader) is missing or corrupted.","error":"Error: VipsOperation: class 'jpegload' not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://sharp.pixelplumbing.com","github":"https://github.com/lovell/sharp","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/sharp","openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}