Configure imaging

These are the default settings for processing images:

imaging:
  anchor: smart
  avif:
    compression: lossy
    encoderSpeed: 10
    hint: photo
    quality: 60
  bgColor: ffffff
  exif:
    disableDate: false
    disableLatLong: false
    excludeFields: GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance
    includeFields: ''
  jpeg:
    quality: 75
  meta:
    fields:
    - '! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*'
    sources:
    - exif
    - iptc
  resampleFilter: box
  webp:
    compression: lossy
    hint: photo
    method: 2
    quality: 75
    useSharpYuv: false

[imaging]
  anchor = 'smart'
  bgColor = 'ffffff'
  resampleFilter = 'box'
  [imaging.avif]
    compression = 'lossy'
    encoderSpeed = 10
    hint = 'photo'
    quality = 60
  [imaging.exif]
    disableDate = false
    disableLatLong = false
    excludeFields = 'GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance'
    includeFields = ''
  [imaging.jpeg]
    quality = 75
  [imaging.meta]
    fields = ['! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*']
    sources = ['exif', 'iptc']
  [imaging.webp]
    compression = 'lossy'
    hint = 'photo'
    method = 2
    quality = 75
    useSharpYuv = false

{
   "imaging": {
      "anchor": "smart",
      "avif": {
         "compression": "lossy",
         "encoderSpeed": 10,
         "hint": "photo",
         "quality": 60
      },
      "bgColor": "ffffff",
      "exif": {
         "disableDate": false,
         "disableLatLong": false,
         "excludeFields": "GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance",
         "includeFields": ""
      },
      "jpeg": {
         "quality": 75
      },
      "meta": {
         "fields": [
            "! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*"
         ],
         "sources": [
            "exif",
            "iptc"
         ]
      },
      "resampleFilter": "box",
      "webp": {
         "compression": "lossy",
         "hint": "photo",
         "method": 2,
         "quality": 75,
         "useSharpYuv": false
      }
   }
}

Top-level settings

These settings apply to all image formats.

anchor

(string) The focal point used when cropping or filling an image. Valid case-insensitive options include TopLeft, Top, TopRight, Left, Center, Right, BottomLeft, Bottom, BottomRight, or Smart. The Smart option utilizes the muesli/smartcrop package to identify the most interesting area of the image. Default is smart.

bgColor

(string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB hexadecimal color. Default is #ffffff.

compression

Deprecated in v0.163.0

Use the format-specific compression setting instead, applicable to AVIF and WebP images.

hint

Deprecated in v0.163.0

Use the format-specific hint setting instead, applicable to AVIF and WebP images.

quality

Deprecated in v0.163.0

Use the format-specific quality setting instead, applicable to AVIF, JPEG, and WebP images.

resampleFilter

(string) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common case-insensitive options include box, lanczos, catmullRom, mitchellNetravali, linear, or nearestNeighbor. Default is box.

Filter	Description
box	Simple and fast averaging filter appropriate for downscaling
lanczos	High-quality resampling filter for photographic images yielding sharp results
catmullRom	Sharp cubic filter that is faster than the Lanczos filter while providing similar results
mitchellNetravali	Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
linear	Bilinear resampling filter, produces smooth output, faster than cubic filters
nearestNeighbor	Fastest resampling filter, no antialiasing

Refer to the source documentation for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.

AVIF

These settings apply when encoding AVIF images.

imaging:
  avif:
    compression: lossy
    encoderSpeed: 10
    hint: photo
    quality: 60

[imaging]
  [imaging.avif]
    compression = 'lossy'
    encoderSpeed = 10
    hint = 'photo'
    quality = 60

{
   "imaging": {
      "avif": {
         "compression": "lossy",
         "encoderSpeed": 10,
         "hint": "photo",
         "quality": 60
      }
   }
}

compression

New in v0.163.0

(string) The encoding strategy. Options are lossy or lossless. Default is lossy.

encoderSpeed

(int) The encoder speed. Expressed as a whole number from 1 to 10, inclusive, equivalent to the -s flag for the avifenc CLI. Lower numbers reduce file size at the cost of build time. At typical web image sizes, quality is indistinguishable across settings. Values below 5 may cause significantly longer build times. Default is 10.

hint

New in v0.163.0

(string) The content hint. Valid options include drawing, icon, photo, picture, or text. Hugo uses the 4:2:0 chroma subsampling format with photo and picture, and 4:4:4 with the remaining options. Default is photo.

Value	Example
drawing	Hand or line drawing with high-contrast details
icon	Small colorful image
photo	Outdoor photograph with natural lighting
picture	Indoor photograph such as a portrait
text	Image that is primarily text

quality

New in v0.163.0

(int) The visual fidelity when using lossy compression. Expressed as a whole number from 1 to 100, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is 60. Quality values are encoder-specific and not directly comparable across formats; a value of 60 for AVIF is perceptually similar to 75 for JPEG.

JPEG

These settings apply when encoding JPEG images.

imaging:
  jpeg:
    quality: 75

[imaging]
  [imaging.jpeg]
    quality = 75

{
   "imaging": {
      "jpeg": {
         "quality": 75
      }
   }
}

quality

(int) The visual fidelity. Expressed as a whole number from 1 to 100, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is 75.

WebP

These settings apply when encoding WebP images.

imaging:
  webp:
    compression: lossy
    hint: photo
    method: 2
    quality: 75
    useSharpYuv: false

[imaging]
  [imaging.webp]
    compression = 'lossy'
    hint = 'photo'
    method = 2
    quality = 75
    useSharpYuv = false

{
   "imaging": {
      "webp": {
         "compression": "lossy",
         "hint": "photo",
         "method": 2,
         "quality": 75,
         "useSharpYuv": false
      }
   }
}

compression

New in v0.163.0

(string) The encoding strategy. Options are lossy or lossless. Default is lossy.

hint

(string) The content hint, equivalent to the -preset flag for the cwebp CLI. Valid options include drawing, icon, photo, picture, or text. Default is photo.

Value	Example
drawing	Hand or line drawing with high-contrast details
icon	Small colorful image
photo	Outdoor photograph with natural lighting
picture	Indoor photograph such as a portrait
text	Image that is primarily text

method

(int) The effort level of the compression algorithm. Expressed as a whole number from 0 to 6, inclusive, equivalent to the -m flag for the cwebp CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency and image quality. Default is 2.

quality

New in v0.163.0

(int) The visual fidelity when using lossy compression. Expressed as a whole number from 1 to 100, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is 75.

useSharpYuv

(bool) The conversion method used for RGB-to-YUV encoding, equivalent to the -sharp_yuv flag for the cwebp CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is false.

Exif method

Meta method

The following parameters allow you to control how Hugo extracts and filters metadata when using the [Meta][] method, helping you balance data granularity with build performance.

fields

([]string) A glob slice matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to ['**'] to include all fields.

By default, to improve performance and decrease cache size, Hugo excludes the following fields: ColorSpace, Contrast, Exif, ExposureBias, ExposureMode, ExposureProgram, Flash, GPS, JPEG, Metering, Resolution, Saturation, Sensing, Sharp, and WhiteBalance.

sources

([]string) The metadata sources to include, one or more of exif, iptc, or xmp. Default is ['exif', 'iptc']. The XMP metadata is excluded by default to improve performance.