# gatsby-transformer-sharp

> Gatsby transformer plugin for images using Sharp

Latest version **5.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-transformer-sharp
pnpm add gatsby-transformer-sharp
yarn add gatsby-transformer-sharp
bun add gatsby-transformer-sharp
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.16.0 |
| Published | 2026-01-26 |
| First published | 2017-04-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 8 |
| Unpacked size | 151.7 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 55941 |
| Author | Kyle Mathews |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin, image, sharp |

## Links

- npm: https://www.npmjs.com/package/gatsby-transformer-sharp
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-sharp#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-transformer-sharp

## Dependencies (8)

- [sharp](https://npm.io/package/sharp.md) ^0.32.6
- [semver](https://npm.io/package/semver.md) ^7.5.3
- [bluebird](https://npm.io/package/bluebird.md) ^3.7.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^11.2.0
- [common-tags](https://npm.io/package/common-tags.md) ^1.8.2
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13
- [probe-image-size](https://npm.io/package/probe-image-size.md) ^7.2.3
- [gatsby-plugin-utils](https://npm.io/package/gatsby-plugin-utils.md) ^4.16.0

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 5.16.0 (latest) — 2026-01-26
- 5.17.0-next.0 (next) — 2025-11-27
- 5.17.0-react19.2 (react19) — 2025-11-26
- 5.13.0-alpha-alt-image-cdn.44 (alt-image-cdn) — 2023-11-03
- 5.9.0-image-cdn-configurable.4 (image-cdn-configurable) — 2023-04-11
- 3.15.0 (latest-v3) — 2022-12-07
- 4.25.0 (latest-v4) — 2022-12-07
- 5.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 4.24.1-alpha-wordpress-image-err.27 (wordpress-image-err) — 2022-11-09
- 4.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 5.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 4.25.0-alpha-image-cdn-pathprefix.48 (image-cdn-pathprefix) — 2022-10-07
- 4.23.0-alpha-image-cdn-enc.40 (image-cdn-enc) — 2022-09-16
- 4.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14
- 4.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- … 561 more at https://npm.io/package/gatsby-transformer-sharp/versions

## README

# gatsby-transformer-sharp

Creates `ImageSharp` nodes from image types that are supported by the
[Sharp](https://github.com/lovell/sharp) image processing library and provides
fields in their GraphQL types for processing your images in a variety of ways
including resizing, cropping, and creating responsive images.

[Live demo](https://image-processing.gatsbyjs.org/)
([source](https://github.com/gatsbyjs/gatsby/tree/master/examples/image-processing))

## Install

```shell
npm install gatsby-transformer-sharp gatsby-plugin-sharp
```

## How to use

```javascript
// In your gatsby-config.js
module.exports = {
  plugins: [`gatsby-plugin-sharp`, `gatsby-transformer-sharp`],
}
```

Please note that you must have a source plugin (which brings in images) installed in your project. Otherwise, no `ImageSharp` nodes can be created for your files. Examples would be [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem) or source plugins for (headless) CMSs like [`gatsby-source-wordpress`](/plugins/gatsby-source-wordpress).

**Note**: An exception to this is when using [`gatsby-source-contentful`](/plugins/gatsby-source-contentful/), as the source plugin and the assets are not [downloaded to the local filesystem](https://www.gatsbyjs.com/plugins/gatsby-source-contentful/#download-assets-for-static-distribution). By default, the `gatsby-source-contentful` plugin creates a `ContentfulAsset` node for every image with links to Contentful’s CDN, therefore it is not necessary to use `gatsby-transformer-sharp` together with `gatsby-source-contentful`.

## Parsing algorithm

It recognizes files with the following extensions as images.

- jpeg
- jpg
- png
- webp
- tif
- tiff

Each image file is parsed into a node of type `ImageSharp`.

## Configuration options

`checkSupportedExtensions` [boolean][optional]

Sharp only supports certain image formats (see the Parsing algorithm section above) and hence throws a warning when you e.g. use a .gif in an `ImageSharp` query. You'll need to use `publicURL` instead. With this option you can disable the warning behavior.

```javascript
// In your gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-transformer-sharp`,
      options: {
        // The option defaults to true
        checkSupportedExtensions: false,
      },
    },
  ],
}
```

## Troubleshooting

### Incompatible library version: sharp.node requires version X or later, but Z provides version Y

This means that there are multiple incompatible versions of the `sharp` package installed in `node_modules`. The complete error typically looks like this:

```text
Something went wrong installing the "sharp" module

dlopen(/Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node, 1): Library not loaded: @rpath/libglib-2.0.dylib
  Referenced from: /Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node
  Reason: Incompatible library version: sharp.node requires version 6001.0.0 or later, but libglib-2.0.dylib provides version 5801.0.0
```

To fix this, you'll need to update all Gatsby plugins in the current project that depend on the `sharp` package. Here's a list of official plugins that you might need to update in case your projects uses them:

- `gatsby-plugin-sharp`
- `gatsby-plugin-manifest`
- `gatsby-remark-images-contentful`
- `gatsby-source-contentful`
- `gatsby-transformer-sharp`
- `gatsby-transformer-sqip`

To update these packages, run:

```shell
npm install gatsby-plugin-sharp gatsby-plugin-manifest gatsby-remark-images-contentful gatsby-source-contentful gatsby-transformer-sharp gatsby-transformer-sqip
```

If updating these doesn't fix the issue, your project probably uses other plugins from the community that depend on a different version of `sharp`. Try running `npm list sharp` or `yarn why sharp` to see all packages in the current project that use `sharp` and try updating them as well.

---
_Source: https://npm.io/package/gatsby-transformer-sharp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._