Table of Contents

Configuration

Most applications can use ImageSharp exactly as it comes out of the box. Configuration only becomes interesting when you need to change what formats are available, how memory is allocated, how streams are read, or how aggressively work is parallelized.

That is why this page treats configuration as an opt-in advanced topic. Start with Configuration.Default, and customize only the parts your workload truly needs.

Use a Local Configuration for Targeted Overrides

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats;

Configuration config = Configuration.Default.Clone();
config.MaxDegreeOfParallelism = 2;
config.PreferContiguousImageBuffers = true;

DecoderOptions options = new()
{
    Configuration = config
};

using Image image = Image.Load(options, stream);

This pattern is usually better than mutating Configuration.Default when the override only matters for one pipeline.

What Configuration Controls

The main knobs on Configuration are:

Register a Specific Format Set

Configuration can be created with an explicit set of IImageFormatConfigurationModule registrations:

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats.Gif;
using SixLabors.ImageSharp.Formats.Jpeg;
using SixLabors.ImageSharp.Formats.Png;

Configuration config = new(
    new PngConfigurationModule(),
    new JpegConfigurationModule(),
    new GifConfigurationModule());

This is useful when you want a deliberately restricted format set for a service or plugin boundary. For more advanced scenarios, ImageFormatManager also exposes methods such as SetEncoder(...), SetDecoder(...), and AddImageFormatDetector(...).

Tune Processor Defaults

ImageSharp stores some processor defaults through Configuration.Properties. A common example is GraphicsOptions:

using SixLabors.ImageSharp;

Configuration config = Configuration.Default.Clone();
config.SetGraphicsOptions(options =>
{
    options.Antialias = false;
    options.BlendPercentage = 0.75F;
});

Those defaults then flow into processing APIs that read graphics options from the current configuration or processing context.

Parallelism and Throughput

MaxDegreeOfParallelism defaults to the machine processor count. That is often a good default for desktop and batch workloads.

For server-side applications running many requests at once, lowering this value on a local configuration can improve overall throughput by avoiding excessive per-image parallel work.

Stream Behavior

ReadOrigin controls whether decoding starts at the current stream position or the beginning of a seekable stream.

StreamProcessingBufferSize controls the buffer size used when ImageSharp copies stream data internally. Most applications should leave it alone unless profiling shows a reason to change it.

When to Customize Configuration

Use a custom or cloned configuration when:

  • You want a restricted set of supported formats.
  • You need a custom MemoryAllocator.
  • You want different parallelism settings for a specific workload.
  • You need contiguous buffers for interop.
  • You need different stream-origin behavior for a pipeline that reads partially consumed streams.

Practical Guidance

  • Use the default configuration unless you have a specific format, allocator, parallelism, or stream behavior to change.
  • Clone configuration for targeted overrides instead of mutating global defaults.
  • Restrict formats at trust boundaries when your workload only supports a known subset.
  • Profile before changing allocator, buffer, or parallelism settings.
Edit this page