Image processing

Image resources

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

Page resource

A page resource is a file within a page bundle. A page bundle is a directory with an index.md or _index.md file at its root.

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

To access an image as a page resource:

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

Global resource

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

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

To access an image as a global resource:

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

Remote resource

A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:

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

Image rendering

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

Example 1: Throws 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: Skips 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: Skips rendering if there’s problem accessing a remote resource.

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

Image processing methods

The image resource implements the Process, Resize, Fit, Fill, Crop, Filter, Colors and Exif methods.

Process

Process processes the image with the given specification. The specification can contain an optional action, one of resize, crop, fit or fill. This means that you can use this method instead of Resize, Fit, Fill, or Crop.

See Options for available options.

You can also use this method apply image processing that does not need any scaling, e.g. format conversions:

{{/* Convert the image from JPG to PNG. */}}
{{ $png := $jpg.Process "png" }}

Some more examples:

{{/* Rotate the image 90 degrees counter-clockwise. */}}
{{ $image := $image.Process "r90" }}

{{/* Scaling actions. */}}
{{ $image := $image.Process "resize 600x" }}
{{ $image := $image.Process "crop 600x400" }}
{{ $image := $image.Process "fit 600x400" }}
{{ $image := $image.Process "fill 600x400" }}

Resize

Resize an image to the given width and/or height.

If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.

{{/* Resize to a width of 600px and preserve aspect ratio */}}
{{ $image := $image.Resize "600x" }}

{{/* Resize to a height of 400px and preserve aspect ratio */}}
{{ $image := $image.Resize "x400" }}

{{/* Resize to a width of 600px and a height of 400px */}}
{{ $image := $image.Resize "600x400" }}

Fit

Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.

{{ $image := $image.Fit "600x400" }}

Fill

Crop and resize an image to match the given dimensions. You must provide both width and height. Use the anchor option to change the crop box anchor point.

{{ $image := $image.Fill "600x400" }}

Crop

Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the anchor option to change the crop box anchor point.

{{ $image := $image.Crop "600x400" }}

Filter

Apply one or more filters to an image.

{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

Write this in a more functional style using pipes. Hugo applies the filters in the order given.

{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

Sometimes it can be useful to create the filter chain once and then reuse it.

{{ $filters := slice  (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $image1 := $image1.Filter $filters }}
{{ $image2 := $image2.Filter $filters }}

Colors

.Colors returns a slice of hex strings with the dominant colors in the image using a simple histogram method.

{{ $colors := $image.Colors }}

This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image.

EXIF

Provides an EXIF object containing image metadata.

You may access EXIF data in JPEG, PNG, TIFF, and WebP images. To prevent errors when processing images without EXIF data, wrap the access in a with statement.

{{ with $image.Exif }}
  Date: {{ .Date }}
  Lat/Long: {{ .Lat }}/{{ .Long }}
  Tags:
  {{ range $k, $v := .Tags }}
    TAG: {{ $k }}: {{ $v }}
  {{ end }}
{{ end }}

You may also access EXIF fields individually, using the lang.FormatNumber function to format the fields as needed.

{{ with $image.Exif }}
  <ul>
    {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
    {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
    {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
    {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
    {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
    {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
  </ul>
{{ end }}

EXIF methods

Date

(time.Time) Returns the image creation date/time. Format with the [time.Format]function.

Lat

(float64) Returns the GPS latitude in degrees.

Long

(float64) Returns the GPS longitude in degrees.

Tags

(exif.Tags) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the site configuration.

Image processing options

The Resize, Fit, Fill, and Crop methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant.

Dimensions

With the Resize method you must specify width, height, or both. The Fit, Fill, and Crop methods require both width and height. All dimensions are in pixels.

{{ $image := $image.Resize "600x" }}
{{ $image := $image.Resize "x400" }}
{{ $image := $image.Resize "600x400" }}
{{ $image := $image.Fit "600x400" }}
{{ $image := $image.Fill "600x400" }}
{{ $image := $image.Crop "600x400" }}

Rotation

Rotates an image counter-clockwise by the given angle. Hugo performs rotation before scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%:

{{ $image = $image.Resize "200x r90" }}

In the example above, the width represents the desired width after rotation.

To rotate an image without scaling, use the dimensions of the original image:

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

In the example above, on the second line, we have reversed width and height to reflect the desired dimensions after rotation.

Anchor

When using the Crop or Fill method, the anchor determines the placement of the crop box. You may specify TopLeft, Top, TopRight, Left, Center, Right, BottomLeft, Bottom, BottomRight, or Smart.

The default value is Smart, which uses Smartcrop image analysis to determine the optimal placement of the crop box. You may override the default value in the site configuration.

For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:

{{ $image.Crop "200x100 TopLeft" }}

If you apply rotation when using the Crop or Fill method, specify the anchor relative to the rotated image.

Target format

By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying bmp, gif, jpeg, jpg, png, tif, tiff, or webp.

{{ $image.Resize "600x webp" }}

To convert an image without scaling, use the dimensions of the original image:

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

Quality

Applicable to JPEG and WebP images, the q value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.

The default value is 75. You may override the default value in the site configuration.

{{ $image.Resize "600x webp q50" }}

Hint

Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the -preset flag for the cwebp encoder.

The default value is photo. You may override the default value in the site configuration.

{{ $image.Resize "600x webp picture" }}

Background color

When converting an image from a format that supports transparency (e.g., PNG) to a format that does not support transparency (e.g., JPEG), you may specify the background color of the resulting image.

Use either a 3-digit or 6-digit hexadecimal color code (e.g., #00f or #0000ff).

The default value is #ffffff (white). You may override the default value in the site configuration.

{{ $image.Resize "600x jpg #b31280" }}

Resampling filter

You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:

The default value is Box. You may override the default value in the site configuration.

{{ $image.Resize "600x400 Lanczos" }}

See github.com/disintegration/imaging for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.

Image processing examples

The photo of the sunset used in the examples below is Copyright Bjørn Erik Pedersen (Creative Commons Attribution-Share Alike 4.0 International license)

This is the shortcode used to generate the examples above:

{{- /*
Renders the given image using the given process specification.

@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource.
@param {string}} (positional parameter 1) The image processing specification.

@returns template.HTML

@example {{< imgproc "sunset.jpg" "resize 300x" />}}
*/}}

{{- with $.Get 0 }}
  {{- with $i := $.Page.Resources.Get . }}
    {{- with $spec := $.Get 1 }}
      {{- with $i.Process . }}
        <figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
          <img style="max-width: 100%; width: auto; height: auto;" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
          <figcaption>
            <small>
              {{- with $.Inner }}
                {{ . }}
              {{- else }}
                {{ $spec }}
              {{- end }}
            </small>
          </figcaption>
        </figure>
      {{- end }}
    {{- else }}
      {{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }}
    {{- end }}
  {{- else }}
    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
  {{- end }}
{{- else }}
  {{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }}
{{- end }}

Call the shortcode from your Markdown like this:

{{< imgproc "sunset.jpg" "resize 300x" />}}

Imaging configuration

Processing options

Define an imaging section in your site configuration to set the default image processing options.

imaging:
  bgColor: '#ffffff'
  hint: photo
  quality: 75
  resampleFilter: box

[imaging]
  bgColor = '#ffffff'
  hint = 'photo'
  quality = 75
  resampleFilter = 'box'

{
   "imaging": {
      "bgColor": "#ffffff",
      "hint": "photo",
      "quality": 75,
      "resampleFilter": "box"
   }
}

anchor

See image processing options: anchor.

bgColor

See image processing options: background color.

hint

See image processing options: hint.

quality

See image processing options: quality.

resampleFilter

See image processing options: resampling filter.

EXIF data

Define an imaging.exif section in your site configuration to control the availability of EXIF data.

imaging:
  exif:
    disableDate: false
    disableLatLong: false
    excludeFields: ""
    includeFields: ""

[imaging]
  [imaging.exif]
    disableDate = false
    disableLatLong = false
    excludeFields = ''
    includeFields = ''

{
   "imaging": {
      "exif": {
         "disableDate": false,
         "disableLatLong": false,
         "excludeFields": "",
         "includeFields": ""
      }
   }
}

disableDate

Hugo extracts the image creation date/time into .Date. Set this to true to disable. Default is false.

disableLatLong

Hugo extracts the GPS latitude and longitude into .Lat and .Long. Set this to true to disable. Default is false.

excludeFields

Regular expression matching the EXIF tags to exclude from the .Tags collection. Default is "".

includeFields

Regular expression matching the EXIF tags to include in the .Tags collection. Default is "". To include all available tags, set this value to ".*".

Smart cropping of images

By default, Hugo uses the Smartcrop library when cropping images with the Crop orFill methods. You can set the anchor point manually, but in most cases the Smart option will make a good choice.

Examples using the sunset image from above:

Image processing performance consideration

Hugo caches processed images in the resources directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.

If you change image processing methods or options, or if you rename or remove images, the resources directory will contain unused images. To remove the unused images, perform garbage collection with:

hugo --gc