Astro optimises images that live in your project’s src folder (or come from authorised remote domains) using its Image and Picture components and a build-time image service. It resizes, converts formats and sets dimensions for you, but only if images are stored and referenced the right way. Images in the public folder are never processed.
This article reflects Astro’s documentation at the time of writing (November 2026). Check the docs for your installed version.
Where the image lives decides everything
According to the Astro docs, src/ is the recommended location for local images because Astro can transform, optimise and bundle them. Files in public/ are served as-is with no processing, and remote images are processed only if their source is authorised; otherwise they display unchanged (Astro Docs: Images).
| Location | Processed? | Use for |
|---|---|---|
src/ |
Yes | Photos, hero images, content images |
public/ |
No | Favicons and files needing a fixed URL |
| Remote, authorised | Yes | CMS or asset library images |
| Remote, not authorised | No | Avoid for performance-critical images |
Image or Picture?
<Image /> outputs an optimised <img> and can change dimensions, file type and quality. <Picture /> outputs a <picture> element with several formats, such as AVIF and WebP, plus a fallback. Both require alt text. Neither works inside plain .md files, though both work in .astro and .mdx. A plain <img> tag is not processed (Astro Docs: Images).
Use Image for most cases. Use Picture when you want to offer modern formats with a safe fallback.
Responsive output
Astro’s layout property generates srcset and sizes automatically, with constrained and full-width layouts getting resizing styles. You can set image.layout globally, which also applies to Markdown images. Responsive output creates several sizes per image, which adds build time (Astro Docs: Images).
If you do not use layout, the API reference describes two manual routes: widths (which must be paired with sizes) or densities, but not both. Densities are ignored when a layout is set (Astro Docs: Image API reference). The automatically generated sizes assumes the image is close to full width on small screens, so multi-column layouts may need a manual value.
Layout shift and loading priority
Setting width and height prevents Cumulative Layout Shift, one of the Core Web Vitals. Astro infers dimensions for local images it can process. For remote images, either set dimensions or use inferSize, which reads them from the file (Astro Docs: Image API reference). For background on the metrics, see Core Web Vitals for business.
For the main above-the-fold image, the priority prop sets eager loading, synchronous decoding and high fetch priority. Use it on one image per page, such as the main hero, not on everything.
Settings worth reviewing
- Quality. Accepts presets (
low,mid,high,max) or a number from 0 to 100. Test visually before lowering it site-wide. - Format. The default output is WebP. Use
Pictureif you also want AVIF. - Remote domains. List trusted hosts in
image.domainsorimage.remotePatterns. - Image service. Sharp is the default. With strict package managers like pnpm you may need to install it manually, and adapters without Sharp support can use
passthroughImageService(), which skips transformation but keepsaltenforcement and layout shift protection (Astro Docs: Images).
A short checklist
- Store content images in
src/, notpublic/. - Write meaningful
alttext. - Use
layoutor a deliberatewidthsandsizespair. - Mark only the hero as
priority. - Authorise remote domains you actually use.
- Check the built page weight, not just the source.
Limits
Optimisation cannot fix an oversized source or a poor crop. It also adds build work, which matters on sites with thousands of images. For a wider comparison with other platforms, see Astro vs WordPress, and for how speed connects to results see what makes a business website convert.
Where Radiance Impact fits
Radiance Impact’s Digital Technology division builds business websites and redesigns, and maintains them afterwards. To discuss site performance, see /technology or reach out through /contact.
Sources
- Images, Astro Docs
- Image and Assets API Reference, Astro Docs
