Image processing

Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only processable images can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.

Resources

To process an image you must capture the file as a page resource, a global resource, or a remote resource.

Page

A page resource is a file within a page bundle.

content/
└── posts/
    └── post-1/           <-- page bundle
        ├── index.md
        └── sunset.jpg    <-- page resource

To capture an image as a page resource:

{{ $image := .Resources.Get "sunset.jpg" }}

Global

A global resource is file within the assets directory, or within any directory mounted to the assets directory.

assets/
└── images/
    └── sunset.jpg    <-- global resource

To capture an image as a global resource:

{{ $image := resources.Get "images/sunset.jpg" }}

Remote

A remote resource is a file on a remote server, accessible via HTTP or HTTPS.

To capture an image as a remote resource:

{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}

Rendering

Once you have captured an image as a resource, render it in your templates using the Permalink, RelPermalink, Width, and Height methods.

Example 1: Throw an error if the resource is not found.

{{ $image := .Resources.GetMatch "sunset.jpg" }}
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">

Example 2: Skip image rendering if the resource is not found.

{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

Example 3: A more concise way to skip image rendering if the resource is not found.

{{ with .Resources.GetMatch "sunset.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

Example 4: Skip rendering if there’s problem accessing a remote resource.

{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
{{ with try (resources.GetRemote $url) }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else with .Value }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ else }}
    {{ errorf "Unable to get remote resource %q" $url }}
  {{ end }}
{{ end }}

Image operations

Use these functions to determine which operations Hugo supports for a given resource. While Hugo classifies a variety of file types as image resources, its ability to process them or extract metadata varies by format.

• reflect.IsImageResource: Reports whether the given value is a Resource object representing an image as defined by its media type.
• reflect.IsImageResourceProcessable: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and perform processing such as converting, resizing, cropping, or filtering.
• reflect.IsImageResourceWithMeta: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and, if present, Exif, IPTC, and XMP data.

The table below shows the values these functions return for various file formats. Use it to determine which checks are required before calling specific methods in your templates.

This contrived example demonstrates how to iterate through resources and use these functions to apply the appropriate handling for each image format.

{{ range resources.Match "**" }}
  {{ if reflect.IsImageResource . }}
    {{ if reflect.IsImageResourceProcessable . }}
      {{ with .Process "resize 300x webp" }}
        <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
      {{ end }}
    {{ else if reflect.IsImageResourceWithMeta . }}
      <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
    {{ else }}
      <img src="{{ .RelPermalink }}" alt="">
    {{ end }}
  {{ end }}
{{ end }}

Processing

To transform an image, apply a processing method to the image resource. Hugo generates the processed image on demand, caches the result, and returns a new resource object.

{{ with .Resources.Get "sunset.jpg" }}
  {{ with .Resize "400x" }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:

Performance

Caching

Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the file cache section of your project configuration.

If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds:

[caches]
  [caches.images]
    dir = ':cacheDir/images'

Garbage collection

If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo’s garbage collection:

hugo build --gc

Resource usage

The time and memory required to process an image increase with the image’s dimensions. For example, a 4032x2268 image requires significantly more memory and processing time than a 1920x1080 image.

If your source images are much larger than the maximum size you intend to publish, consider scaling them down before the build to optimize performance.

Configuration

See configure imaging.