An automatic image optimizer for the Sitecore media library. Reduce the size of your images served from Sitecore by 8-70%, completely automatically.
Dianoga ensures that your site is always serving fully optimised media library images even if you are using Sitecore's dynamic resizing features. Even if you have already optimized every image uploaded into the media library, after Sitecore performs image processing the result is not optimized (an unfortunate limitation of most other image optimization libraries for Sitecore is that they only apply to the original image).
Dianoga is also great for situations where content editors may not be image editing experts and upload images that contain gobs of EXIF data and other nonessential metadata - these are removed automatically before being shown to visitors.
- JPEGs (via mozjpeg - lossless or lossy)
- PNGs (via PNGOptimizer - lossless / pngquant - lossy)
- SVGs (via SVGO - lossless, and automatic gzipping of SVG media responses)
- WebP (via cwebp - lossless or lossy)
- Auto convert JPEG/PNG/GIF to WebP based on browser support
Additional format support is possible to add via new processors in the
By default, Dianoga runs asynchronously after the image is saved into the media cache. This means it has practically no effect on the site's frontend performance (though it does use some CPU time in the background). The performance of Dianoga is logged into the Sitecore log. PNGs are very fast because it's a native P/Invoke call to a C DLL - about 20ms for a small one. JPEGs result in executing a program and are slightly slower - around 200ms for a medium sized image. Larger images several MB in size can take a second or two depending on the hardware in use.
Once the image is in cache for the requested size, there is no performance penalty as the file is read from the media cache unless it is changed again.
Note that because the cache is updated after the first image request, the first hit to images will result in the unoptimized version being served, to preserve the responsiveness of the request. Subsequent requests will receive the optimized version from cache.
Dianoga depends on the Dianoga Tools folder that is installed by the NuGet package into the web project it is installed on. You can relocate these tools if you wish by changing the paths in the
In Dianoga, you can choose your optimization strategy. Most people if serving media locally are best off with the defaults, which optimize the media as it is placed into the media cache. This results in minimal impact to the experience for front end visitors.
However, for folks using CDNs those sources must be sent the optimized version of the media immediately. For these situations, you can enable
Dianoga.Strategy.GetMediaStreamSync.config.disabled and disable
Dianoga.Strategy.MediaCacheAsync.config. This will cause optimization to occur synchronously as the media is first requested, which is appropriate if the media is being sent to a CDN. This may however cause a delay for the first hit user before they start seeing images.
If you want to execute the Dianoga optimization pipeline programmatically (e.g. as part of a CDN upload background process), you can use the
MediaOptimizer class to execute optimization on any Sitecore
MediaStream object at will.
Dianoga 3+ allows for ignoring specific paths in the media library. See
Dianoga.ExcludePaths.config.example for an example of this.
Dianoga 5+ has a NuGet package for the main code and configs, and a separate package for the SVGO tools -
Dianoga.svgtools. This was done as SVGO is an 80MB library.
Once Dianoga is installed, clear your App_Data/MediaCache folder, and you're done.
To perform a manual installation:
- Copy the
Dianoga Toolsfolder to the
App_Datafolder of your website
Default Config Files/*.configto
Dianoga.dllor the source project in your web project
WebP is is an image format employing both lossy and lossless compression. It is currently developed by Google, based on technology acquired with the purchase of On2 Technologies. WebP file size is 25%-34% smaller compared to JPEG file size and 26% smaller for PNG. All evergreen browsers except Safari currently support WebP. By default WebP optimization is disabled since you need to do some due diligence around reviewing configs, how it works, and importantly if you are using a CDN you need to do some extra steps.
How WebP optimization works:
Browser sends request to server to get image. If browser supports WebP image format then it sends "image/webp" value in Accept header. It is possible to detect this header on server and return WebP image to browser instead of JPEG or PNG. If browser doesn't support WebP then other image optimizers are executed if they are enabled.
How to enable WebP support:
Dianoga.WebP.config.disabledconfig and adjust any parameters if you require lossless or higher quality than the default
- Open web.config and change line
<add verb="*" path="sitecore_media.ashx" type="Sitecore.Resources.Media.MediaRequestHandler, Sitecore.Kernel" name="Sitecore.MediaRequestHandler" />
<add verb="*" path="sitecore_media.ashx" type="Dianoga.MediaRequestHandler, Dianoga" name="Sitecore.MediaRequestHandler" />
OR if you use SXA
<add verb="*" path="sitecore_media.ashx" type="Dianoga.MediaRequestHandlerXA, Dianoga" name="Sitecore.MediaRequestHandler" />
OR if you have a custom
MediaRequestHandler then you need to make some changes - see
- If you run Sitecore under CDN: review and enable
Upgrading from any previous version of Dianoga is fairly simple.
- Upgrade the NuGet package.
- Remove any
App_Config\Include\Dianoga.configthat may exist (config has changed, you must reapply settings if changed in the new scheme)
Dianoga Toolsif it exists (Dianoga 3+ places tools under App_Data\Dianoga Tools instead so that IIS defaults to not serving anything there)
- Delete your MediaCache folder (defaults to App_Data/MediaCache) on all servers after deployment of Dianoga (otherwise unoptimized caches will remain present)
- Have fun.
If you're not seeing optimization take place, there are a couple of possibilities:
- The image might already be in the media cache (by default,
/App_Data/MediaCache). Sitecore does not reprocess images in cache until needed, so Dianoga may never be called. Delete this folder, clear your browser cache or use ctrl-F5, and try again.
- The image may be in your browser cache. Check using the browser's network tab or Fiddler that Sitecore was not returning a
HTTP 304 Not Modifiedresponse code for the media. If it was, the media cache was not evaluated for the response. Try a hard refresh instead.
- An error is occurring. The Sitecore logs catch all errors that occur when generating a media stream, so look there first. If an error occurs, the result of the pipeline is thrown away and the unmodified stream returned so you may not see broken images if this occurs, just oddly sized - if resizing - or unoptimized ones.
You can optimize any type of image that the media library supports with Dianoga.
Adding a new
Processor to the config will enable you to call a micro-pipeline you define to process that type.
Optimizer micro-pipeline you can add or remove optimizers that are applied in order to the specified file type.
Comments are available in the config files and source for your perusal.