---
title: Image processing
description: Transform images to change their size, shape, and appearance.
categories: []
keywords: []
---
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](g) 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" %}}
```text
content/
└── posts/
└── post-1/ <-- page bundle
├── index.md
└── sunset.jpg <-- page resource
```
To capture an image as a page resource:
```go-html-template
{{ $image := .Resources.Get "sunset.jpg" }}
```
### Global
{{% glossary-term "global resource" %}}
```text
assets/
└── images/
└── sunset.jpg <-- global resource
```
To capture an image as a global resource:
```go-html-template
{{ $image := resources.Get "images/sunset.jpg" }}
```
### Remote
{{% glossary-term "remote resource" %}}
To capture an image as a remote resource:
```go-html-template
{{ $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.
```go-html-template
{{ $image := .Resources.GetMatch "sunset.jpg" }}
```
Example 2: Skip image rendering if the resource is not found.
```go-html-template
{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
{{ end }}
```
Example 3: A more concise way to skip image rendering if the resource is not found.
```go-html-template
{{ with .Resources.GetMatch "sunset.jpg" }}
{{ end }}
```
Example 4: Skip rendering if there's problem accessing a remote resource.
```go-html-template
{{ $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.
```go-html-template
{{ 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:
```toml
[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:
```text
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](/configuration/imaging).
[`Height`]: /methods/resource/height/
[`Meta`]: /methods/resource/meta/
[`Permalink`]: /methods/resource/permalink/
[`RelPermalink`]: /methods/resource/relpermalink/
[`Width`]: /methods/resource/width/
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[file cache]: /configuration/caches/