Shopify img_url Filter Is Obsolete — Complete Migration to image_url
The img_url filter powered Shopify image URLs for years and still technically works. But it has been replaced by image_url, which unlocks Shopify's next-generation Image CDN: automatic WebP and AVIF format negotiation, responsive srcset generation, and proper width/height attributes that eliminate Cumulative Layout Shift. Themes still on img_url leave significant performance gains on the table and fail Theme Check validation. This guide covers every migration pattern you need.
What changed between img_url and image_url
img_url was a string filter that appended size parameters to a CDN URL: {{ image | img_url: '800x' }}. image_url is a method on Shopify image objects: {{ image | image_url: width: 800 }}. The critical difference: image_url URLs are served with automatic format negotiation — browsers that support WebP receive WebP, AVIF-capable browsers receive AVIF, reducing image payload by 25-40%. img_url always delivered the original format with no negotiation.
Core migration patterns
Simple width: {{ image | img_url: '800x' }} becomes {{ image | image_url: width: 800 }}. Master size: {{ image | img_url: 'master' }} becomes {{ image | image_url: width: image.width }}. Fixed dimensions with crop: {{ image | img_url: '400x400', crop: 'center' }} becomes {{ image | image_url: width: 400, height: 400, crop: 'center' }}. Available crop values: center, top, bottom, left, right.
Using image_tag for automatic CWV compliance
Chain image_url with image_tag to generate a complete img element with all Core Web Vitals attributes: {{ product.featured_image | image_url: width: 800 | image_tag: loading: 'eager', fetchpriority: 'high', alt: product.featured_image.alt }}. image_tag automatically adds explicit width and height attributes matching the image dimensions, eliminating CLS. Hero images: loading eager + fetchpriority high. All other images: loading lazy.
Responsive srcset with the widths parameter
Generate a complete srcset in one line: {{ product.featured_image | image_url: width: 1200 | image_tag: widths: '400,800,1200', sizes: '(min-width: 768px) 50vw, 100vw', loading: 'lazy', alt: product.featured_image.alt }}. The browser picks the optimal width for every viewport and device pixel ratio, typically reducing image payload by 40-60% on mobile compared to a single large image.
The fix: before and after
// CODE_COMPARISON
Frequently asked questions
- Will img_url stop working on my live store?
Shopify has not announced a removal date. Live themes continue to function. However, img_url fails Theme Check with an ObsoleteFilter warning, is blocked in Theme Store submissions, and misses all CDN optimization features. For any active development, migrate to image_url.
- Does image_url work on all Shopify image objects?
image_url works on product.images items, variant.image, collection.image, article.image, page.image, metafield values of type image_reference or file_reference, and Shopify File objects. It does not work on plain URL strings — you need an actual Shopify image object.
- How do I safely handle a nil image object?
Always check for nil before calling image_url: {% if product.featured_image != blank %}{{ product.featured_image | image_url: width: 800 | image_tag }}{% endif %}. Calling image_url directly on nil raises a Liquid rendering error that outputs a blank section.
// SCAN_YOUR_CODE
Does your theme have this bug?
Paste your code. Syphio automatically detects and fixes this error and hundreds of others — in seconds.
Validate my Liquid →