Memory optimization for image-heavy builds

[jornmineur]

*EDIT Jan 26, 2026: a PR that resolves this issue is ready for review.

---

Summary

On a website with:

• 1200+ unique images,
• 600+ pages using standard eleventy-img image shortcodes (no WebC),
• multiple responsive formats (AVIF, JPEG) and sizes per image,

... memory usage reaches 90GB, causing memory swapping and system freezes.

Setup:

• OS: macOS 15.5 (M2 Max, 32GB RAM)
• Node: v22.11.0
• @11ty/eleventy-img: 6.0.1
• @11ty/eleventy: 3.1.2

With a custom patch, memory footprint was reduced by 96% and build time by 60%.

Suggestion is to add a similar patch to eleventy-img.

Alternative workarounds tried

Changing concurrency settings in eleventy-img or old space settings in V8 has no effect.

Root Cause Analysis

1. Buffer Caching: Image.#contents stores source image buffers without eviction
2. Instance Caching: memCache retains all Image instances for the entire build lifecycle
3. Linear Growth: Memory usage grows linearly with unique images processed

// Current behavior in Image class
class Image {
  #contents = {};
  
  async getFileContents() {
    // Buffers are cached indefinitely
    if (!this.#contents[src]) {
      this.#contents[src] = await fs.readFile(src);
    }
    return this.#contents[src];
  }
}

Expected Behavior

Memory usage should remain bounded regardless of the number of images processed, especially when:

• Images are processed once and outputs are reused
• The same responsive image formats/sizes are generated consistently
• Disk cache already exists for processed images

Proposed Solution

Add an optional manifest-based caching system that:

1. Tracks processed images with metadata (dimensions, formats, URLs)
2. Detects changes via file modification time/size
3. Skips reprocessing for unchanged images
4. Reduces memory by avoiding unnecessary Image instantiation

Suggested API

// Option 1: Global configuration
eleventyConfig.addPlugin(eleventyImagePlugin, {
  manifestPath: ".cache/image-manifest.json",
  enableManifest: process.env.NODE_ENV === "production"
});

// Option 2: Per-image configuration
await Image(src, {
  widths: [300, 600],
  formats: ["avif", "jpeg"],
  useManifest: true,
  manifestPath: ".cache/image-manifest.json"
});

Manifest Structure

{
  "./src/images/hero.jpg": {
    "fingerprint": {
      "mtime": 1234567890,
      "size": 123456
    },
    "outputs": {
      "avif": [
        { "width": 300, "height": 200, "filename": "xYz123-300.avif" },
        { "width": 600, "height": 400, "filename": "xYz123-600.avif" }
      ],
      "jpeg": [
        { "width": 300, "height": 200, "filename": "xYz123-300.jpeg" },
        { "width": 600, "height": 400, "filename": "xYz123-600.jpeg" }
      ]
    }
  }
}

Proof of Concept Results

Results of a custom implementation wrapping eleventy-img:

Metric	Before	After	Improvement
Memory Usage	90GB	3.2GB	-96%
Build Time (cached)	5 min	2 min	-60%

Backwards Compatibility

• Manifest usage would be opt-in
• Existing behavior unchanged without explicit configuration
• Falls back gracefully if manifest is corrupted/missing

[Aankhen]

This sounds like a big improvement. I do wonder whether maintaining a manifest file is a prerequisite for reducing memory usage, though. Given that the root cause is holding on to image data, if the plugin instead tracked only metadata as described above within each build, all builds would benefit without any major downsides.

My intuition is that images are rarely reused in exactly the same way within a build, so the rare cost of reading the handful of exceptions from disk multiple times should be fairly irrelevant. The manifest would then be an optional means of avoiding reprocessing images at all.

[zeroby0]

Currently, tracking changes is done via hashing the images contents, and processing is skipped if an image with the same filename in the hash exists in the output folder. We call this the on-disk cache.

The in-memory cache was implemented before on-disk cache was added, to prevent processing images a second time during a single eleventy run. But now since we have on-disk cache, maybe we can retire the in-memory cache behind a config option?

[zeroby0]

Or maybe we can patch the add and get methods in https://github.com/11ty/eleventy-img/blob/main/src/memory-cache.js to evict objects (possibly to disk) if the number of objects is higher than a certain (possibly configurable) amount?

[GoOz]

I have the exact same issue on my side (see #281), It's preventing me from upgrading 11ty-img to v6. Somehow some previous versions were not as much affected.
I have 600+ hi-res images on my website and I add one almost everyday. Everyday I have just one picture and a tiny md file to process, it shouldn't need gigabytes of ram to process those 2 files.
I'm not even sure how much it consumes exactly because I payed for a 4Gb of memory hosting solution and my provider kills the process when it reaches the limit, so right now I'm stuck with an old version (v2.0.1) but I don't know for how long because even this version needs gigabytes, just not 4Gb yet… but it's growing.

Meanwhile @jornmineur if you have a simple workaround I could use, I'd be in your debt. 😅

[jornmineur]

@GoOz my workaround is not that simple I'm afraid :-)

Here's a gist explaining the idea: https://gist.github.com/jornmineur/4604225396aac010ec1f862489cd6df2

[GoOz]

Hello there,
Is there even an idea of an ETA for this kind of fix?
@jornmineur's workaround is a lot of rework for a "temporary" solution to be honest.
I'm seeing there's a v7 on the work, would it be possible to have this fix implemented in it?

[zeroby0]

@GoOz I don't think there's any ETA because the maintainer hasn't agreed to implement it in the first place.

What happens if you disable the in-memory cache and let the browser load images from the on-disk cache instead?

The latest commit on v7 was 7 months ago. I wouldn't hold my breath for it :)

[zeroby0]

ref: #313

cache pollution means the same images are being cached multiple times.