Netlify Docs
Ask Netlify

Contact

Netlify Image CDN

This feature is in Beta.

With Netlify Image CDN, you can transform images on demand without impacting build times. Netlify Image CDN also handles content negotiation to use the most efficient image format for the requesting client. Optimizing the size and format of your images improves both the runtime performance and reliability of your site. Transformations are integrated natively into the CDN so that repeated requests leverage layers of caching for improved performance.

To transform an image, make a request to /.netlify/images with query parameters that specify the source asset and the desired transformations.

After an image is transformed, the result is uniquely cached on our edge and future requests for the same transformation will serve the cached asset. We also cache the source image so that future transformations don’t have to download it again. Netlify Image CDN respects atomic deploys. If you change a previously transformed source image in a new deploy, we re-run transformations on new requests so that we don’t serve outdated assets.

# Transform images

Use query parameters on your requests to /.netlify/images to specify the following transformation options:

You must specify a source asset with the url parameter as described below. All other parameters are optional.

Query validation and response codes

When a request is made to /.netlify/images, we validate the query parameters.

  • If any transformation parameters have invalid values, we return a 404.
  • If the query parameters are valid and the request is for a new transformation, we return a 200 with the requested content and content-type.
  • If the request is for a previously transformed image, we return a 304.

For interactive examples of the different parameters, visit our demo site.

# Source

You must specify a source image with the url parameter. You can use either a relative or a remote path to your source image.

Source-only transformations

If you include only a source url in your transformation request, we don’t change the size or shape of your image. But, we do transform the format to avif or webp according to which formats are supported by the user’s browser.

# Relative path

No configuration is required for relative paths to source images.

Here’s an example transformation request using a relative path to an image on the site’s domain.

# transform the source image deployed at https://mysitename.netlify.app/owl.jpeg
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg'

# Remote path

To transform a source image hosted on another domain, you must first configure allowed domains in your netlify.toml file using the images key.

[images]
  remote_images = ["https://my-images.com/.*", "https://animals.more-images.com/[bcr]at/.*"]

The remote_images property accepts an array of regex. If your images are in specific subdomains or directories, you can use regex to allow just those subdomains or directories.

After configuring allowed domains for remote images, you can request transformations of assets hosted on the allowed domains. Here’s an example transformation request using a remote path to an image on another domain.

# transform the source image hosted at https://my-images.com/owl.jpeg
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=https://my-images.com/owl.jpeg'

# Size

To change the size of an image, use the following parameters with integers to specify the target size in pixels.

  • w: width
  • h: height
# resize the image to 50 px wide
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'

How these parameters are applied depends on the fit option for the request. By default, fit=contain.

# Fit

To control how an image is resized, use the fit parameter. Supported values are as follows:

The fit parameter works in conjunction with the w and h size parameters. The fit value affects things such as whether or not the aspect ratio is maintained and whether or not the requested dimensions are always returned.

# resize and crop the image to 50 pixels square
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50'

Here’s a comparison of the different fit options. They each behave in the same way as their equivalent CSS object-fit values. For more information, including example images, read the option-specific sections below.

fit= source aspect ratio always maintained excess pixels cropped requested dimensions always returned
contain yes no no, one dimension may be smaller
cover no yes yes, image scaled proportionally before cropping
fill no no yes, image stretched and squished if needed

# fit=contain (default)

Fit within the specified dimensions and maintain the source aspect ratio by resizing the image proportionally. If you supply just one dimension, the other is calculated to maintain the aspect ratio of the source image. If you supply two dimensions and the target aspect ratio is different than the source aspect ratio, one dimension of the resulting image matches the requested size while the other is smaller.

Examples. Original image is 400 by 310. Contain width 600 and height 600 enlarges image proportionally to 600 by 465. Contain width 200 and height 400 shrinks image proportionally to 200 by 155.

# fit=cover

Fill the specified dimensions without distortion by resizing the image proportionally, then cropping out any excess pixels. By default, the center of the image is retained with the left and right or top and bottom cropped evenly. To control what part of the image is retained, use the position parameter.

To use fit=cover, you must supply both w and h.

Examples. Original image is 400 by 310. Cover width 200 and height 310 crops out excess pixels from left and right without resizing. Cover width 500 and height 150 enlarges image to new width then crops excess pixels from top and bottom. Cover width 150 and height 150 resizes image to new height then crops excess pixels from left and right.

# fit=fill

Fill the specified dimensions exactly. If the target aspect ratio is different than the source aspect ratio, the image is stretched and squished as needed to fill the target dimensions.

Examples. Original image is 400 by 310. Images are distorted to fill new dimensions. Fill width 200 and height 400 stretches image vertically. Fill width 300 and height 100 squishes image vertically. Fill width 150 and height 150 slightly stretches image vertically.

# Position

To control how an image is cropped when fit=cover, use the position parameter. Supported values are as follows:

  • top
  • bottom
  • left
  • right
  • center (default)

The value represents what part of the image to retain when cropping.

# resize the image and retain the left side when cropping
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left'

# Format

To change the format of an image, use the fm parameter. Supported values are as follows:

  • avif
  • jpg
  • png
  • webp
  • blurhash - returns a string that you can use to render a blurred placeholder image. Visit BlurHash to learn more.
# convert a jpeg into png
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=png'

# resulting image includes an appropriate `content-type` response header
< HTTP/2 200
< content-type: image/png

If you don’t specify a format, we inspect the Accept header for content negotiation with the following logic:

  1. use avif if accepted
  2. otherwise, use webp if accepted
  3. if neither is accepted, use the original format

# Quality

To control the output quality of a lossy conversion, use the q parameter. This applies when the target format is avif, jpg, or webp.

The q parameter supports whole integers from 1 to 100. The default is 75.

# convert a jpeg into avif with medium quality
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=avif&q=50'

# Redirects and rewrites

You can use redirects and rewrites with Netlify Image CDN. This can be helpful, for example, if you want to reuse the same parameters for multiple images.

/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200

[[redirects]]
  from = "/transform-small/*"
  to = "/.netlify/images?url=/:splat&w=50&h=50"
  status = 200

With the above redirect in place, you can make transformation requests like the following:

# transform the source image deployed at https://mysitename.netlify.app/owl.jpeg
# to a size of 50px wide by 50px high per the parameters in the redirect
curl -vs 'https://mysitename.netlify.app/transform-small/owl.jpeg'

Cross-site redirects are not recommended

Cross-site redirects for image transformations are not recommended. They could negatively impact your site’s performance.

# Limitations

Keep the following limitations in mind when working with Netlify Image CDN:

  • Split Testing is not supported. You may get inconsistent image results between your split test branches.
  • Visitor access controls are not supported. A request for an image on a secured path returns a 403.

# Feedback

We welcome your feedback on this feature. Visit our Forums to join the conversation about Netlify Image CDN.