gatsbyjs/gatsby · error

Please install gatsby-plugin-sharp

Error message

Please install gatsby-plugin-sharp

What it means

In writeImage (image-processing.ts:197-201), the plugin dynamically requires 'gatsby-plugin-sharp' to access generateImageData, which computes responsive image dimensions, formats, and srcset entries. If the require fails (module not found), reporter.panic fires. gatsby-plugin-sharp is the actual image transformation engine that gatsby-plugin-image depends on at build time.

Source

Thrown at packages/gatsby-plugin-image/src/node-apis/image-processing.ts:200

    }
  )

  return Promise.all(promises).then(() => {})
}

export async function writeImage(
  file: FileSystemNode,
  args: ISharpGatsbyImageArgs,
  pathPrefix: string,
  reporter: Reporter,
  cache: GatsbyCache,
  filename: string
): Promise<void> {
  let generateImageData
  try {
    generateImageData = require(`gatsby-plugin-sharp`).generateImageData
  } catch (e) {
    reporter.panic(`Please install gatsby-plugin-sharp`)
  }
  try {
    const options = { file, args, pathPrefix, reporter, cache }

    if (!generateImageData) {
      reporter.warn(`Please upgrade gatsby-plugin-sharp`)
      return
    }
    // get standard set of fields from sharp
    const sharpData = await generateImageData(options)

    if (sharpData) {
      // Write the image properties to the cache
      await fs.writeJSON(filename, sharpData)
    } else {
      reporter.warn(`Could not process image ${file.relativePath}`)
    }
  } catch (e) {

View on GitHub (pinned to 8b06340921)

Solutions

1. Install gatsby-plugin-sharp: npm install gatsby-plugin-sharp gatsby-transformer-sharp
2. Add both to gatsby-config.js plugins array
3. Verify version compatibility with your gatsby-plugin-image version

Example fix

// before: only gatsby-plugin-image installed
// after: package.json + gatsby-config.js
dependencies: {
  "gatsby-plugin-image": "^2.0.0",
  "gatsby-plugin-sharp": "^4.0.0",
  "gatsby-transformer-sharp": "^4.0.0",
}

// gatsby-config.js
plugins: [
  `gatsby-plugin-image`,
  `gatsby-transformer-sharp`,
  `gatsby-plugin-sharp`,
]

// Pre-build check for gatsby-plugin-sharp
try {
  require.resolve('gatsby-plugin-sharp')
  const { generateImageData } = require('gatsby-plugin-sharp')
  if (typeof generateImageData !== 'function') {
    console.error('gatsby-plugin-sharp is installed but generateImageData is missing — upgrade required')
  }
} catch {
  console.error('gatsby-plugin-sharp is required by gatsby-plugin-image')
  process.exit(1)
}

When it happens

Trigger: Using gatsby-plugin-image (<StaticImage> or <GatsbyImage>) without gatsby-plugin-sharp installed. The require('gatsby-plugin-sharp') throws MODULE_NOT_FOUND.

Common situations: Fresh project that added gatsby-plugin-image but not gatsby-plugin-sharp. Upgrading Gatsby versions where gatsby-plugin-sharp was split out as a separate dependency. Monorepo resolution issues.

Related errors

• Please install gatsby-source-filesystem
• Gatsby-plugin-sharp wasn't setup correctly in gatsby-config.
• Processing ${file} failed
• error converting image
• Specified dimensions for images must be positive numbers (>

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/eb6483a6a545b323. Report an issue: GitHub.