When using the Astro Image component, the docs say By default, the <Image /> component will produce a .webp file. Why then is a .jpg image not being output as .webp unless explicitly specifying format="webp" in the Image component?
#Image component and webp default
random gyro
celest ginkgoBOT
Hi @random gyro. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
By default, the Astro <Image /> component is designed to output images in the .webp format, as stated in the documentation: "By default, the <Image /> component will produce a .webp file" Image format property.
However, if you are seeing that a .jpg image is not being output as .webp unless you explicitly set format="webp", there could be a few reasons:
-
Default Behavior: The documentation clearly states the default output is
.webp, so you should not need to specifyformat="webp"for this to happen. The expected behavior is that, when you use<Image src={myJpg} alt="..." />, the output should be a.webpfile unless you override the format. -
Component Usage: Make sure you are using the
<Image />component fromastro:assetsand not a plain<img>tag. The default.webpoutput only applies to the<Image />component, not to<img>tags, which will use the original file format Astro components for images. -
Image Location: If your image is in the
public/folder or is a remote image, Astro will not optimize or transform it, and the output will remain in the original format. Only images imported from thesrc/directory are processed and optimized by Astro Image properties. -
Image Service Configuration: If you have customized your image service in
astro.config.mjs, it could affect the output format. The default service is Sharp, but if you have changed this or are using a passthrough/no-op service, images may not be transformed Default image service.
If you are following the documented usage and still not seeing .webp output, double-check that:
- The image is imported from
src/ - You are using the
<Image />component - No custom image service is overriding the default behavior
If all of these are correct and the issue persists, it may be a bug or an environment-specific issue not covered in the documentation.
Summary:
By default, <Image /> should output .webp files for local images in src/ without needing to specify format="webp". If this is not happening, check your usage and configuration as described above. The knowledge sources do not mention any exceptions to this default behavior other than those listed here.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
random gyro
@celest ginkgo the image is in /src, but because i need to access its url from a variable theImage, I can't import it in the frontmatter of the component. So I'm using src={theImage.url} in the Image component
celest ginkgoBOT
Let me check the knowledge base for you again. One moment! :books:
If you are using the Astro <Image /> component and passing a string URL (e.g., src={theImage.url}) instead of an imported image object, Astro will not optimize or transform the image—even if the file is in your src/ directory. The optimization (including default .webp output) only happens when you import the image directly in the frontmatter and pass the imported object to the src prop (e.g., src={myImage}) Image properties.
When you use a string path (like src={theImage.url}), Astro treats it the same as an image from the public/ folder or a remote URL, and outputs the image as-is, without converting it to .webp or performing any optimizations. This is why you are not seeing a .webp output in this case.
If you need to dynamically import images from src/, you can use Vite’s import.meta.glob to import images and then pass the imported image object to the <Image /> component. This approach allows you to retain Astro’s optimization features, including default .webp output. See the Dynamically import images recipe for more details.
Summary:
Astro only optimizes and outputs .webp by default when you pass an imported image object to <Image />. Passing a string URL disables optimization, so the image is not converted to .webp Image properties.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
random gyro
@celest ginkgo going with the "dynamically import images recipe", the image path is stated with a path alias, but the keys in import.meta.glob do not use aliases. is there a way to reconcile aliased paths with unaliased to make a match?
celest ginkgoBOT
Let me check the knowledge base for you again. One moment! :books:
The knowledge sources confirm that when using import.meta.glob, the keys in the resulting object are always the literal file paths as matched by the glob pattern, and these do not use your configured import aliases. For example, if you use:
const images = import.meta.glob('/src/assets/*.{jpeg,jpg,png,gif}');
The keys will look like /src/assets/avatar-1.jpg, not @assets/avatar-1.jpg or any alias form. The documentation does not mention any built-in way to automatically reconcile or map between aliased paths and the unaliased keys returned by import.meta.glob Glob Patterns Dynamically import images recipe.
If you want to use aliases in your props or elsewhere, you would need to manually map or normalize the paths in your code to match the keys used by import.meta.glob. The documentation does not provide a built-in utility or recommended approach for this reconciliation.