How to Add Images to an Astro Site

Astro can take a big image and turn it into a small, modern one while your site builds. In our test, a 62 kB PNG became a 5 kB WebP file, with no visible change. Here’s how to use it.

Step 1: Add your image to the project

Create a folder called src/images and put your picture in it. For this guide, we’ll call it team-photo.png.

Keep images inside src whenever you can. Files in public are copied exactly as they are, with no optimization.

Step 2: Use the Image component

Open the page where you want the picture, and add two imports and one tag:

---
import { Image } from 'astro:assets';
import teamPhoto from '../images/team-photo.png';
---
<Image src={teamPhoto} alt="Our team standing outside the office." width={600} />

The alt text is required. It’s what screen readers read out, and it helps search engines understand the picture.

Because the image is imported from src, Astro knows its real size. The width tells Astro how large to make the optimized version.

Step 3: Build and look at the result

Run npm run build. In the output you’ll see a line like this:

▶ /_astro/team-photo.CroshMPU_Z1Oj0fM.webp (before: 62kB, after: 5kB)

Astro converted the image to WebP, resized it, and gave it a unique file name so browsers can cache it safely. The HTML it produces also includes loading="lazy", so images lower down the page don’t load until needed.

Images in Markdown

In a blog post written in Markdown, use the normal image syntax with a relative path:

![A starry night sky.](../../images/stars.png)

Images referenced this way from src are optimized too. The Image component itself isn’t available in .md files, only in .astro and .mdx files.

Pictures in several formats

To serve AVIF where the browser supports it, with a fallback, use the Picture component:

---
import { Picture } from 'astro:assets';
import teamPhoto from '../images/team-photo.png';
---
<Picture src={teamPhoto} formats={['avif', 'webp']} alt="Our team standing outside the office." />

Images from other websites

Astro only optimizes remote images from sites you approve. Add them to astro.config.mjs:

export default defineConfig({
  image: {
    domains: ['example.com'],
  },
});

Remote images also need a width and height, because Astro can’t read their size in advance.

Frequently asked questions

Should images go in src or public?

Put them in src when you can, so Astro can optimize them. Use public only for files that must keep their exact name and bytes, like a favicon.

Why does Astro want alt text?

The alt text describes the image for people who can't see it, and for search engines. Astro's Image component requires it. For a purely decorative image, use alt="".

Can I use images from another website?

Yes, by giving the full address as the src. Astro only optimizes remote images from sites you list in your config, and it needs a width and height for them.