| 1 |
--- |
| 2 |
title: Image processing |
| 3 |
description: Transform images to change their size, shape, and appearance. |
| 4 |
categories: [] |
| 5 |
keywords: [] |
| 6 |
--- |
| 7 |
|
| 8 |
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. |
| 9 |
|
| 10 |
> [!note] |
| 11 |
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed. |
| 12 |
|
| 13 |
## Resources |
| 14 |
|
| 15 |
To process an image you must capture the file as a page resource, a global resource, or a remote resource. |
| 16 |
|
| 17 |
### Page |
| 18 |
|
| 19 |
{{% glossary-term "page resource" %}} |
| 20 |
|
| 21 |
```text |
| 22 |
content/ |
| 23 |
└── posts/ |
| 24 |
└── post-1/ <-- page bundle |
| 25 |
├── index.md |
| 26 |
└── sunset.jpg <-- page resource |
| 27 |
``` |
| 28 |
|
| 29 |
To capture an image as a page resource: |
| 30 |
|
| 31 |
```go-html-template |
| 32 |
{{ $image := .Resources.Get "sunset.jpg" }} |
| 33 |
``` |
| 34 |
|
| 35 |
### Global |
| 36 |
|
| 37 |
{{% glossary-term "global resource" %}} |
| 38 |
|
| 39 |
```text |
| 40 |
assets/ |
| 41 |
└── images/ |
| 42 |
└── sunset.jpg <-- global resource |
| 43 |
``` |
| 44 |
|
| 45 |
To capture an image as a global resource: |
| 46 |
|
| 47 |
```go-html-template |
| 48 |
{{ $image := resources.Get "images/sunset.jpg" }} |
| 49 |
``` |
| 50 |
|
| 51 |
### Remote |
| 52 |
|
| 53 |
{{% glossary-term "remote resource" %}} |
| 54 |
|
| 55 |
To capture an image as a remote resource: |
| 56 |
|
| 57 |
```go-html-template |
| 58 |
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} |
| 59 |
``` |
| 60 |
|
| 61 |
## Rendering |
| 62 |
|
| 63 |
Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods. |
| 64 |
|
| 65 |
Example 1: Throw an error if the resource is not found. |
| 66 |
|
| 67 |
```go-html-template |
| 68 |
{{ $image := .Resources.GetMatch "sunset.jpg" }} |
| 69 |
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}"> |
| 70 |
``` |
| 71 |
|
| 72 |
Example 2: Skip image rendering if the resource is not found. |
| 73 |
|
| 74 |
```go-html-template |
| 75 |
{{ $image := .Resources.GetMatch "sunset.jpg" }} |
| 76 |
{{ with $image }} |
| 77 |
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> |
| 78 |
{{ end }} |
| 79 |
``` |
| 80 |
|
| 81 |
Example 3: A more concise way to skip image rendering if the resource is not found. |
| 82 |
|
| 83 |
```go-html-template |
| 84 |
{{ with .Resources.GetMatch "sunset.jpg" }} |
| 85 |
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> |
| 86 |
{{ end }} |
| 87 |
``` |
| 88 |
|
| 89 |
Example 4: Skip rendering if there's problem accessing a remote resource. |
| 90 |
|
| 91 |
```go-html-template |
| 92 |
{{ $url := "https://gohugo.io/img/hugo-logo.png" }} |
| 93 |
{{ with try (resources.GetRemote $url) }} |
| 94 |
{{ with .Err }} |
| 95 |
{{ errorf "%s" . }} |
| 96 |
{{ else with .Value }} |
| 97 |
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> |
| 98 |
{{ else }} |
| 99 |
{{ errorf "Unable to get remote resource %q" $url }} |
| 100 |
{{ end }} |
| 101 |
{{ end }} |
| 102 |
``` |
| 103 |
|
| 104 |
{{% include "/_common/functions/reflect/image-reflection-functions.md" %}} |
| 105 |
|
| 106 |
## Processing |
| 107 |
|
| 108 |
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. |
| 109 |
|
| 110 |
```go-html-template |
| 111 |
{{ with .Resources.Get "sunset.jpg" }} |
| 112 |
{{ with .Resize "400x" }} |
| 113 |
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> |
| 114 |
{{ end }} |
| 115 |
{{ end }} |
| 116 |
``` |
| 117 |
|
| 118 |
> [!note] |
| 119 |
> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats. |
| 120 |
|
| 121 |
Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements: |
| 122 |
|
| 123 |
{{% render-table-of-pages-in-section |
| 124 |
path=/methods/resource |
| 125 |
filter=methods_resource_image_processing |
| 126 |
filterType=include |
| 127 |
headingColumn1=Method |
| 128 |
headingColumn2=Description |
| 129 |
%}}{class="!mt-0"} |
| 130 |
|
| 131 |
## Performance |
| 132 |
|
| 133 |
### Caching |
| 134 |
|
| 135 |
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. |
| 136 |
|
| 137 |
If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds: |
| 138 |
|
| 139 |
```toml |
| 140 |
[caches] |
| 141 |
[caches.images] |
| 142 |
dir = ':cacheDir/images' |
| 143 |
``` |
| 144 |
|
| 145 |
### Garbage collection |
| 146 |
|
| 147 |
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: |
| 148 |
|
| 149 |
```text |
| 150 |
hugo build --gc |
| 151 |
``` |
| 152 |
|
| 153 |
### Resource usage |
| 154 |
|
| 155 |
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. |
| 156 |
|
| 157 |
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. |
| 158 |
|
| 159 |
## Configuration |
| 160 |
|
| 161 |
See [configure imaging](/configuration/imaging). |
| 162 |
|
| 163 |
[`Height`]: /methods/resource/height/ |
| 164 |
[`Meta`]: /methods/resource/meta/ |
| 165 |
[`Permalink`]: /methods/resource/permalink/ |
| 166 |
[`RelPermalink`]: /methods/resource/relpermalink/ |
| 167 |
[`Width`]: /methods/resource/width/ |
| 168 |
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/ |
| 169 |
[file cache]: /configuration/caches/ |