Netlify Image CDN
Transform images by requesting /.netlify/images with query parameters. No function or file authoring required — it's a built-in edge endpoint.
# resize + crop to a 50px square, retain left side, convert to webp at q=80
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left&fm=webp&q=80'
There is no legacy/deprecated form — the endpoint above is the only programmatic surface. Use framework image components where available (below) rather than hand-building URLs.
Endpoint & query parameters
GET /.netlify/images?url=<source>&...
| Param |
Values |
Notes |
url |
relative path or full remote URL |
REQUIRED. Only required param. |
w |
integer px |
width |
h |
integer px |
height |
fit |
contain (default), cover, fill |
resize behavior |
position |
center (default), top, bottom, left, right |
only applies when fit=cover |
fm |
avif, jpg, png, webp, gif, blurhash |
output format; webp/gif can be animated |
q |
integer 1–100 (default 75) |
only for avif, jpg, gif, webp |
fit behavior
fit= |
aspect ratio kept |
crops excess |
returns exact dimensions |
contain |
yes |
no |
no — one dimension may be smaller |
cover |
no |
yes |
yes — scaled proportionally, then cropped |
fill |
no |
no |
yes — stretched/squished if needed |
fit=cover requires BOTH w and h. Supplying only one silently misbehaves.
contain with one dimension calculates the other to preserve aspect ratio.
Format & content negotiation
- Source-only request (just
url, no size/format): image is unchanged in size/shape but still reformatted to avif/webp based on the browser's Accept header.
- No
fm specified → webp if accepted, else avif if accepted, else original.
fm=blurhash returns a BlurHash text string, not image bytes. Pointing <img src> or a CSS background at it renders nothing. Fetch the string server-side/ahead of time, decode it client-side with a BlurHash library (https://blurha.sh), then load the real image as a separate request without fm=blurhash.
Response codes
- Invalid transformation param values →
404.
- Valid, new transformation →
200 with content + content-type.
- Previously transformed →
304.
Remote source images
Remote url values require allowlisting the domain in netlify.toml:
[images]
remote_images = ["https://my-images.com/.*", "https://animals.more-images.com/[bcr]at/.*"]
Then percent-encode the remote URL and request it:
const src = `/.netlify/images?url=${encodeURIComponent("https://my-images.com/owl.jpeg")}`;
- Always
encodeURIComponent the remote URL before placing it in url — URLs containing ? or & break otherwise.
- In
remote_images patterns, escape only the dot: 'https://example\.com/.*'. Forward slashes are NOT regex metacharacters — do not write https:\/\/.
- Remote sources must be publicly accessible. Netlify does NOT forward
Authorization or Cookie headers to remote sources. For auth-required images use self-authorizing URLs (e.g. S3 presigned URLs) and make sure your remote_images pattern matches them.
Reusable transformations (redirects)
Reuse the same params across many images via a redirect:
_redirects:
/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200
netlify.toml:
[[redirects]]
from = "/transform-small/*"
to = "/.netlify/images?url=/:splat&w=50&h=50"
status = 200
Then GET /transform-small/owl.jpeg yields a 50×50 transform. Avoid cross-site redirects for transformations — they hurt performance.
Custom headers (caching)
_headers:
/source-images/*
Cache-Control: public, max-age=604800, must-revalidate
- Headers set on a source image are applied to the transformed asset served by Image CDN.
- Custom headers cannot be applied to remote (other-domain) source images; Netlify respects whatever cache headers the external domain sends.
Cache-Control on source images applies only to browsers/CDNs in front of Netlify, not the Netlify Cache itself.
Framework integrations
Use the framework's native image component/handling; it wires to Image CDN automatically. Configure the remote allowlist per framework:
| Framework |
Prerequisite |
Remote allowlist |
| Angular |
none — NgOptimizedImage auto-uses it |
[images] remote_images in netlify.toml |
| Astro |
none — <Image /> auto-uses it |
image.domains / image.remotePatterns in astro.config.mjs |
| Nuxt |
none — nuxt/image auto-uses it |
image.domains in nuxt.config.ts |
| Next.js |
Next 13.5+ and adapter v5 |
remotePatterns in next.config.js |
| Gatsby |
env NETLIFY_IMAGE_CDN=true + Contentful/Drupal/WordPress source plugin |
[images] remote_images in netlify.toml |
Local development
Run netlify dev (Netlify CLI) to test transformations locally — it mimics production including Image CDN.
- A local
404 on /.netlify/images almost always means a framework dev server (vite, next dev, astro dev) is running instead of netlify dev. The endpoint, [images] allowlisting, and image redirects only exist under netlify dev. The URL itself is usually fine.
Caching & deploys
Transformed results are uniquely cached on Netlify's edge. Atomic deploys are respected: changing a source image in a new deploy re-runs transformations on new requests so stale assets aren't served.
User-uploaded image pipelines
For user-uploaded image pipelines (Functions + Blobs + Image CDN composed), see references/user-uploads.md in this skill.
Limitations
- Split Testing is not supported — you may get inconsistent image results between split test branches.
- Not currently supported in Netlify's HIPAA-compliant hosting offering. See the Trust Center for the HIPAA-compliant reference architecture.
Netlify house rules (image-cdn)
These are org conventions, not docs facts — merged into the rendered skill by
ctx-gen and never generated. Owned by the skills maintainer.
- For user-uploaded image pipelines (Functions + Blobs + Image CDN
composed), see
references/user-uploads.md in this skill — an authored
guide with no single docs source.
- Percent-encode remote source URLs before placing them in the
url
parameter (encodeURIComponent) — URLs containing ? or & break
otherwise.
fm=blurhash returns a BlurHash TEXT string, not image bytes. Pointing an
<img src> (or CSS background) at it renders nothing — fetch the string
ahead of time, decode it client-side with a BlurHash library, and load the
real image as a separate request without fm=blurhash.
- A local 404 on
/.netlify/images almost always means a framework dev
server (vite, next dev, astro dev) is running instead of
netlify dev — the endpoint, [images] allowlisting, and image redirects
only exist under netlify dev. The URL itself is usually fine.
- In
remote_images patterns, the meaningful regex escape is the dot;
forward slashes are not metacharacters — do not write https:\/\/.
In netlify.toml, use a single-quoted literal string
('https://example\.com/.*') or double the backslash in a
double-quoted string ("https://example\\.com/.*") — a bare \.
inside double quotes is invalid TOML.
1---
2name: netlify-image-cdn
3description: Transform, resize, crop, reformat, and optimize images on demand via Netlify Image CDN's /.netlify/images endpoint. Use when adding responsive images, generating thumbnails, converting formats (avif/webp/png), cropping to aspect ratios, tuning image quality, creating blurred placeholders, allowlisting remote image domains, serving user-uploaded images, or wiring framework image components (Next.js, Astro, Nuxt, Angular, Gatsby) to Netlify. Triggers on tasks like "optimize images", "add image thumbnails", "resize images on the fly", "serve images from an external domain", or "add blur placeholders".
4metadata:
5 source: https://skillmd.com/skills/netlify/netlify-image-cdn
6---
7
8# Netlify Image CDN
9
10Transform images by requesting `/.netlify/images` with query parameters. No function or file authoring required — it's a built-in edge endpoint.
11
12```bash
13# resize + crop to a 50px square, retain left side, convert to webp at q=80
14curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left&fm=webp&q=80'
15```
16
17There is no legacy/deprecated form — the endpoint above is the only programmatic surface. Use framework image components where available (below) rather than hand-building URLs.
18
19## Endpoint & query parameters
20
21`GET /.netlify/images?url=<source>&...`
22
23| Param | Values | Notes |
24|---|---|---|
25| `url` | relative path or full remote URL | **REQUIRED**. Only required param. |
26| `w` | integer px | width |
27| `h` | integer px | height |
28| `fit` | `contain` (default), `cover`, `fill` | resize behavior |
29| `position` | `center` (default), `top`, `bottom`, `left`, `right` | only applies when `fit=cover` |
30| `fm` | `avif`, `jpg`, `png`, `webp`, `gif`, `blurhash` | output format; `webp`/`gif` can be animated |
31| `q` | integer `1`–`100` (default `75`) | only for `avif`, `jpg`, `gif`, `webp` |
32
33### `fit` behavior
34
35| `fit=` | aspect ratio kept | crops excess | returns exact dimensions |
36|---|---|---|---|
37| `contain` | yes | no | no — one dimension may be smaller |
38| `cover` | no | yes | yes — scaled proportionally, then cropped |
39| `fill` | no | no | yes — stretched/squished if needed |
40
41- **`fit=cover` requires BOTH `w` and `h`.** Supplying only one silently misbehaves.
42- `contain` with one dimension calculates the other to preserve aspect ratio.
43
44### Format & content negotiation
45
46- Source-only request (just `url`, no size/format): image is unchanged in size/shape but **still reformatted** to `avif`/`webp` based on the browser's `Accept` header.
47- No `fm` specified → `webp` if accepted, else `avif` if accepted, else original.
48- `fm=blurhash` returns a BlurHash **text string, not image bytes.** Pointing `<img src>` or a CSS background at it renders nothing. Fetch the string server-side/ahead of time, decode it client-side with a BlurHash library (https://blurha.sh), then load the real image as a separate request without `fm=blurhash`.
49
50### Response codes
51
52- Invalid transformation param values → `404`.
53- Valid, new transformation → `200` with content + `content-type`.
54- Previously transformed → `304`.
55
56## Remote source images
57
58Remote `url` values require allowlisting the domain in `netlify.toml`:
59
60```toml
61[images]
62 remote_images = ["https://my-images.com/.*", "https://animals.more-images.com/[bcr]at/.*"]
63```
64
65Then percent-encode the remote URL and request it:
66
67```js
68const src = `/.netlify/images?url=${encodeURIComponent("https://my-images.com/owl.jpeg")}`;
69```
70
71- **Always `encodeURIComponent` the remote URL** before placing it in `url` — URLs containing `?` or `&` break otherwise.
72- In `remote_images` patterns, **escape only the dot**: `'https://example\.com/.*'`. Forward slashes are NOT regex metacharacters — do not write `https:\/\/`.
73- Remote sources must be **publicly accessible**. Netlify does NOT forward `Authorization` or `Cookie` headers to remote sources. For auth-required images use self-authorizing URLs (e.g. S3 presigned URLs) and make sure your `remote_images` pattern matches them.
74
75## Reusable transformations (redirects)
76
77Reuse the same params across many images via a redirect:
78
79`_redirects`:
80```
81/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200
82```
83
84`netlify.toml`:
85```toml
86[[redirects]]
87 from = "/transform-small/*"
88 to = "/.netlify/images?url=/:splat&w=50&h=50"
89 status = 200
90```
91
92Then `GET /transform-small/owl.jpeg` yields a 50×50 transform. **Avoid cross-site redirects for transformations** — they hurt performance.
93
94## Custom headers (caching)
95
96`_headers`:
97```
98/source-images/*
99 Cache-Control: public, max-age=604800, must-revalidate
100```
101
102- Headers set on a source image are applied to the transformed asset served by Image CDN.
103- Custom headers **cannot** be applied to remote (other-domain) source images; Netlify respects whatever cache headers the external domain sends.
104- `Cache-Control` on source images applies only to browsers/CDNs in front of Netlify, **not** the Netlify Cache itself.
105
106## Framework integrations
107
108Use the framework's native image component/handling; it wires to Image CDN automatically. Configure the remote allowlist per framework:
109
110| Framework | Prerequisite | Remote allowlist |
111|---|---|---|
112| Angular | none — `NgOptimizedImage` auto-uses it | `[images] remote_images` in `netlify.toml` |
113| Astro | none — `<Image />` auto-uses it | `image.domains` / `image.remotePatterns` in `astro.config.mjs` |
114| Nuxt | none — `nuxt/image` auto-uses it | `image.domains` in `nuxt.config.ts` |
115| Next.js | Next 13.5+ and adapter v5 | `remotePatterns` in `next.config.js` |
116| Gatsby | env `NETLIFY_IMAGE_CDN=true` + Contentful/Drupal/WordPress source plugin | `[images] remote_images` in `netlify.toml` |
117
118## Local development
119
120Run `netlify dev` (Netlify CLI) to test transformations locally — it mimics production including Image CDN.
121
122- **A local `404` on `/.netlify/images` almost always means a framework dev server (`vite`, `next dev`, `astro dev`) is running instead of `netlify dev`.** The endpoint, `[images]` allowlisting, and image redirects only exist under `netlify dev`. The URL itself is usually fine.
123
124## Caching & deploys
125
126Transformed results are uniquely cached on Netlify's edge. Atomic deploys are respected: changing a source image in a new deploy re-runs transformations on new requests so stale assets aren't served.
127
128## User-uploaded image pipelines
129
130For user-uploaded image pipelines (Functions + Blobs + Image CDN composed), see `references/user-uploads.md` in this skill.
131
132## Limitations
133
134- **Split Testing is not supported** — you may get inconsistent image results between split test branches.
135- Not currently supported in Netlify's HIPAA-compliant hosting offering. See the Trust Center for the HIPAA-compliant reference architecture.
136
137<!-- system: agent-context/image-cdn/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
138# Netlify house rules (image-cdn)
139
140These are org conventions, not docs facts — merged into the rendered skill by
141ctx-gen and never generated. Owned by the skills maintainer.
142
1431. For user-uploaded image pipelines (Functions + Blobs + Image CDN
144 composed), see `references/user-uploads.md` in this skill — an authored
145 guide with no single docs source.
1462. Percent-encode remote source URLs before placing them in the `url`
147 parameter (`encodeURIComponent`) — URLs containing `?` or `&` break
148 otherwise.
1493. `fm=blurhash` returns a BlurHash TEXT string, not image bytes. Pointing an
150 `<img src>` (or CSS background) at it renders nothing — fetch the string
151 ahead of time, decode it client-side with a BlurHash library, and load the
152 real image as a separate request without `fm=blurhash`.
1534. A local 404 on `/.netlify/images` almost always means a framework dev
154 server (`vite`, `next dev`, `astro dev`) is running instead of
155 `netlify dev` — the endpoint, `[images]` allowlisting, and image redirects
156 only exist under `netlify dev`. The URL itself is usually fine.
1575. In `remote_images` patterns, the meaningful regex escape is the dot;
158 forward slashes are not metacharacters — do not write `https:\/\/`.
159 In `netlify.toml`, use a single-quoted literal string
160 (`'https://example\.com/.*'`) or double the backslash in a
161 double-quoted string (`"https://example\\.com/.*"`) — a bare `\.`
162 inside double quotes is invalid TOML.