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.

[!note] Use the reflect.IsImageResourceProcessable function to verify that an image can be processed.

Resources

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

Page

{{% glossary-term "page resource" %}}

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

{{% glossary-term "global resource" %}}

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

To capture an image as a global resource:

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

Remote

{{% glossary-term "remote resource" %}}

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" }}

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

{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
  
{{ end }}

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

{{ with .Resources.GetMatch "sunset.jpg" }}
  
{{ 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 }}
    
  {{ else }}
    {{ errorf "Unable to get remote resource %q" $url }}
  {{ end }}
{{ end }}

{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}

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" }}
    
  {{ end }}
{{ end }}

[!note] Metadata is not preserved during image transformation. Use the Meta method with the original image resource to extract metadata from supported formats.

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

{{% render-table-of-pages-in-section path=/methods/resource filter=methods_resource_image_processing filterType=include headingColumn1=Method headingColumn2=Description %}}{class="!mt-0"}

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.