Announcing ImageSharp.Web 4.0.0

ImageSharp.Web 4 moves to .NET 8+, builds on ImageSharp 4, and updates web delivery defaults for orientation, ICC conversion, and encoder settings.

ReleasesImageSharp.WebImageSharp

ImageSharp.Web 4.0.0 is out.

ImageSharp.Web 4.0.0 moves the middleware to .NET 8+, adopts ImageSharp 4 as its processing engine, and updates the default behavior used for processed web images: EXIF orientation handling, ICC profile conversion, and encoder settings for JPEG, PNG, and WebP.

The public API stays familiar, but the defaults are not identical to V3. Requests with image-processing commands now get an autoorient=true command inserted when they do not already contain an autoorient command. Default decoder options use ColorProfileHandling.Convert when the middleware is using its default ImageSharp configuration, and the default encoders are configured for web delivery.

ImageSharp.Web is the delivery layer of the Six Labors suite. It sits between ASP.NET Core requests, image providers, caches, command parsing, ImageSharp processing, and encoded output.

V4 is also the first ImageSharp.Web release to enforce a build-time license key for direct package dependencies. More on that below.

What's new since V3 #

  • A .NET 8+ baseline for the middleware
  • ImageSharp 4 as the processing engine
  • Default autoorient=true insertion for command URLs that do not explicitly opt out
  • Default ICC profile normalization through ColorProfileHandling.Convert
  • Web-oriented default encoders for JPEG, PNG, and WebP
  • quality command handling that preserves more options from the configured JPEG and WebP encoders
  • Updated default behavior for applications that rely on the built-in configuration, command parsing callback, or decoder options callback

.NET 8+ and ImageSharp 4 #

ImageSharp.Web 4 now targets .NET 8+ and builds on top of ImageSharp 4.

That gives the middleware the same imaging core used by the rest of the current suite, including the color-management, codec, encoder, and metadata behavior that arrived in ImageSharp 4.

Auto-orient for command URLs #

One practical change in V4 is that ImageSharp.Web now inserts autoorient=true when the command collection is not empty and the request does not already contain an autoorient command.

That is implemented through the default OnParseCommandsAsync callback. The callback leaves raw URLs alone, preserves an explicit autoorient=true or autoorient=false, and only inserts the command when other image-processing commands are already present.

The reason is format and browser behavior. Relying on encoded EXIF orientation alone does not produce consistent results across formats and browsers. WebP in particular has been a long-running source of confusion here, as documented in Exif Orientation in Different Formats. For processed images, V4 normalizes orientation in the pixels unless the caller opts out.

That means command URLs like these now include auto-orientation by default:

/images/photo.jpg?width=400
/images/photo.jpg?width=400&height=250&rmode=crop

A raw URL such as /images/photo.jpg does not get an autoorient=true command inserted by this callback. If the request already has processing commands, the middleware inserts auto-orient before later processors run.

If you replace OnParseCommandsAsync, you also replace that built-in behavior unless you preserve the existing delegate.

Default ICC normalization #

V4 also changes how the middleware handles color.

When you keep the default middleware configuration and do not return custom DecoderOptions from OnBeforeLoadAsync, ImageSharp.Web 4 now decodes with ColorProfileHandling.Convert. That means embedded ICC profiles are normalized into a predictable working space for web-oriented re-encoding.

Source images do not always arrive in the color model that makes sense for the web. JPEGs can carry CMYK or other non-sRGB profile data, while the destination format may be something like WebP with a more constrained color model. Decode-time normalization gives the middleware a predictable working space before it resizes, reformats, and re-encodes the result.

In some of our tests, that change produced output up to roughly 8x smaller from the same request URL.

If you replace options.Configuration, the middleware's fallback decoder behavior changes to ColorProfileHandling.Compact unless you return explicit DecoderOptions yourself.

Upgrade guidance:

  • keep the default configuration if you want the new web-oriented color behavior automatically
  • if you customize the base configuration, also return explicit decoder options so you preserve ColorProfileHandling.Convert

Encoder defaults #

The middleware configuration installs encoder defaults for web delivery:

  • JPEG uses quality 75, progressive output, interleaving, and YCbCrRatio420
  • PNG uses BestCompression and adaptive filtering
  • WebP uses quality 75 with BestQuality

They apply whether the output format comes from the source image or from the format command.

For JPEG, quality 75 balances visible quality and transfer size for normal web photography. Progressive encoding with interleaved scans improves perceived loading because browsers can show a coarse full-color preview from the first scan, and progressive output is often smaller than baseline JPEG. YCbCrRatio420 uses chroma subsampling to reduce color data while preserving luma detail.

For PNG, BestCompression and adaptive filtering favor smaller payloads for screenshots, illustrations, UI assets, and other graphics where PNG is still the right output format. Adaptive filtering lets the encoder choose the filter strategy row by row instead of treating the whole image the same way. That spends more CPU during the initial encode, but ImageSharp.Web is a cache-backed middleware: pay once, cache the result, and serve later requests from storage.

For WebP, quality 75 sets the default quality level, while BestQuality tells the encoder to spend more effort during compression. When the first request pays the heavier encode cost and later requests are served from cache, the result is often smaller output and more predictable bandwidth cost over time.

The quality command now preserves more settings from the configured encoder. For JPEG, custom quality output keeps reference settings such as progressive output, progressive scans, restart interval, interleaving, color type, and metadata behavior. For WebP, it preserves settings such as method, alpha compression, entropy passes, spatial noise shaping, filter strength, transparent color mode, near-lossless settings, and metadata behavior.

Modular when you need it #

The middleware is configurable.

You can replace parsers, caches, providers, processors, cache keys, hashes, converters, callbacks, and the underlying ImageSharp configuration. In V4, those extension points can also replace the new defaults, so custom setups should decide which defaults to preserve.

If you want custom encoder registrations but still want the new ICC-conversion behavior, keep the existing configuration as your base and return explicit decoder options:

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats;
using SixLabors.ImageSharp.Formats.Jpeg;
using SixLabors.ImageSharp.Web;

builder.Services.AddImageSharp(options =>
{
    Configuration configuration = options.Configuration.Clone();

    configuration.ImageFormatsManager.SetEncoder(JpegFormat.Instance, new JpegEncoder
    {
        Quality = 82,
        Progressive = true,
        Interleaved = true,
        ColorType = JpegColorType.YCbCrRatio420
    });

    options.Configuration = configuration;

    options.OnBeforeLoadAsync = (_, _) => Task.FromResult<DecoderOptions?>(new()
    {
        Configuration = configuration,
        ColorProfileHandling = ColorProfileHandling.Convert
    });
});

Likewise, if you override OnParseCommandsAsync, preserve the existing delegate unless you intentionally want to remove the default auto-orientation insertion for command URLs.

Breaking and operational notes #

The two main upgrade notes for V4 are straightforward:

  • the package now targets .NET 8+
  • direct dependencies must provide a sixlabors.lic file at build time

There is also an important behavioral shift to be aware of:

  • command URLs are now auto-oriented by default unless you explicitly disable that behavior
  • default decode behavior now normalizes ICC profiles for web-oriented output
  • replacing the middleware configuration or parse callback can remove those defaults if you do not preserve them deliberately

If you qualify for community licensing, you can apply via licensing.sixlabors.com.

Closing #

ImageSharp.Web 4 moves the middleware to .NET 8+, adopts ImageSharp 4, inserts auto-orientation for command URLs, converts ICC profiles by default when using the built-in configuration, updates JPEG, PNG, and WebP encoder defaults, and preserves more encoder settings when the quality command is used.

Explore the docs, try the new defaults, and let us know what you build with it.

ImageSharp.Web 4.0.0 is licensed under the Six Labors Split License. This means that it is free to use in both non-commercial and certain commercial applications. However, if you are using it in a commercial application and your organization has annual gross revenue exceeding 1M USD per year, you must purchase a commercial license. Please see the Pricing page for more information.