Debian Codegraph @

docs/content/en/content-management/image-processing/index.md

raw
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/