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
- If the query parameters are valid and the request is for a new transformation, we return a
200with the requested content and content-type.
- If the request is for a previously transformed image, we return a
For interactive examples of the different parameters, visit our demo site.
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
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] remote_images = ["https://my-images.com/.*", "https://animals.more-images.com/[bcr]at/.*"]
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'
To change the size of an image, use the following parameters with integers to specify the target size in pixels.
# resize the image to 50 px wide curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'
To control how an image is resized, use the
fit parameter. Supported values are as follows:
fit parameter works in conjunction with the
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.
| ||source aspect ratio always maintained||excess pixels cropped||requested dimensions always returned|
| ||yes||no||no, one dimension may be smaller|
| ||no||yes||yes, image scaled proportionally before cropping|
| ||no||no||yes, image stretched and squished if needed|
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.
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
fit=cover, you must supply both
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.
To control how an image is cropped when
fit=cover, use the
position parameter. Supported values are as follows:
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'
To change the format of an image, use the
fm parameter. Supported values are as follows:
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:
- otherwise, use
- if neither is accepted, use the original format
To control the output quality of a lossy conversion, use the
q parameter. This applies when the target format is
q parameter supports whole integers from
100. The default is
# 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.
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
We welcome your feedback on this feature. Visit our Forums to join the conversation about Netlify Image CDN.
Did you find this doc useful?
Your feedback helps us improve our docs.