Table of Contents

ImageSharp.Web

ImageSharp.Web is Six Labors' high-performance ASP.NET Core image middleware for on-the-fly processing and caching. It sits in front of one or more image providers, parses URL commands, runs the matching ImageSharp processors, and stores the result so repeated requests are inexpensive after the first hit.

The current package targets .NET 8 and is built on top of ImageSharp. The middleware is intentionally modular: you can change how commands are parsed, where source images come from, how cache keys are built, where processed images are stored, and whether image requests must be signed.

The practical model is a web request pipeline. A provider resolves the original image, a parser turns the request into commands, processors transform the image, an encoder writes the response, and a cache stores the result so the next matching request can avoid the expensive work. Most configuration choices are about one of those stages.

Use ImageSharp.Web when image variants are determined by HTTP requests: responsive thumbnails, CDN-backed transformations, signed URLs, tenant-specific providers, or cached format conversion. Use core ImageSharp directly when processing is an offline job, queue worker, or application workflow that is not naturally request-driven.

License

ImageSharp.Web is licensed under the terms of the Six Labors Split License, Version 1.0. See https://sixlabors.com/pricing for commercial licensing details.

Important

Starting with ImageSharp.Web 4.0.0, projects that directly depend on ImageSharp.Web require a valid Six Labors license at build time. This enforcement applies to direct dependencies only. See License Enforcement Changes and a New Subscription Tier for details.

Install ImageSharp.Web

ImageSharp.Web is distributed on NuGet with preview and nightly builds available on Feedz.

PM > Install-Package SixLabors.ImageSharp.Web -Version VERSION_NUMBER

Prerelease versions installed via the Visual Studio NuGet Package Manager require the "include prerelease" checkbox to be checked.

How to use the license file

By default, the build searches from each project directory for sixlabors.lic. Place the supplied file in the directory that contains the project file, or in a subdirectory below it. Use the file as supplied; it already contains the complete license string required by the build.

Important

Do not commit sixlabors.lic or a license key to public repositories such as open source projects. Use environment variables or repository secrets instead, and let contributors apply for their own independent keys at https://licensing.sixlabors.com/.

If you want to keep the file somewhere else, including a repository root that sits above the project directory, set SixLaborsLicenseFile in your project file or a shared props file:

<PropertyGroup>
  <SixLaborsLicenseFile>path/to/sixlabors.lic</SixLaborsLicenseFile>
</PropertyGroup>

If you do not want to store the license on disk, pass the license string directly from an environment variable or secret store. When extracting the value from sixlabors.lic, use the full file contents, not only the Key field:

<PropertyGroup>
  <SixLaborsLicenseKey>$(SIXLABORS_LICENSE_KEY)</SixLaborsLicenseKey>
</PropertyGroup>

You can also pass the key to common .NET CLI commands.

PowerShell:

dotnet build -p:SixLaborsLicenseKey="$env:SIXLABORS_LICENSE_KEY"
dotnet publish -p:SixLaborsLicenseKey="$env:SIXLABORS_LICENSE_KEY"

Bash and other shells that expand environment variables with $NAME:

dotnet build -p:SixLaborsLicenseKey="$SIXLABORS_LICENSE_KEY"
dotnet publish -p:SixLaborsLicenseKey="$SIXLABORS_LICENSE_KEY"

Build as normal after the file or property is configured. If the license is missing or invalid, the build fails with a clear error. You do not need to reference the licensing package directly; it is carried by Six Labors libraries.

Start Here

  • Getting Started covers the minimal ASP.NET Core setup and the default provider and cache behavior.
  • Configuration and Pipeline explains what AddImageSharp() registers, the middleware's default auto-orientation behavior, web-focused encoder defaults, ICC profile handling, and how to replace or reorder the moving parts.
  • Processing Commands documents the built-in resize, auto-orient, format, quality, and background-color commands, including which ones are implicit by default.
  • Image Providers covers filesystem, Azure Blob Storage, and AWS S3 source images.
  • Image Caches covers the default physical cache, cloud cache backends, cache keys, and cache lifetime.
  • Securing Requests explains HMAC signing and preset-only parsing.
  • Tag Helpers covers Razor integration and automatic HMAC generation.
  • Extensibility walks through custom processors, parsers, providers, caches, and converters.
  • Troubleshooting covers the most common middleware-order, provider, cache, and signing problems.

Implicit Usings

Set UseImageSharp in your project file to automatically import the most common ImageSharp and ImageSharp.Web namespaces:

<PropertyGroup>
  <UseImageSharp>true</UseImageSharp>
</PropertyGroup>

When enabled, ImageSharp.Web adds implicit global using directives for:

  • SixLabors.ImageSharp
  • SixLabors.ImageSharp.Processing
  • SixLabors.ImageSharp.Web

You can turn this off by removing the property or setting it to false.

How to Use These Docs

  • Start with getting started and processing commands to understand the default request pipeline.
  • Read configuration, providers, and caches before deploying beyond a single local filesystem setup.
  • Read security before exposing arbitrary command URLs to clients.
  • Use extensibility only after choosing which pipeline stage actually owns the behavior you need.
Edit this page