Shopify Deprecated img_url Filter: How to Migrate to image_url
Search intent: fix · Updated February 2026
Shopify deprecated the img_url Liquid filter in 2022, replacing it with image_url. Themes still using img_url continue to work (Shopify has not removed it), but the old filter cannot leverage Shopify's CDN image transformation improvements, including the ability to use the width and height parameters for native lazy loading with correct aspect ratios. Migrating to image_url also enables the | image_tag filter, which auto-generates correct width, height, srcset, and loading attributes - improving Core Web Vitals (CLS and LCP) without manual HTML.
Quick Diagnostic Checklist
- Search for 'img_url' in your theme code using the Shopify code editor - how many results?
- Run npx shopify theme check - are there LiquidFilter:DeprecatedFilter warnings?
- Check your product image elements in DevTools - do they have explicit width and height attributes?
- Run PageSpeed Insights on a product page - is Cumulative Layout Shift flagged as a problem?
Not sure if your store has this issue?
Run a free scan to detect shopify-specific problems instantly.
What This Issue Means
Shopify's img_url filter produces a single image URL at a fixed size. The newer image_url filter works with Shopify's image transformation pipeline and pairs with the image_tag filter to automatically output responsive images with srcset, correct aspect ratios (preventing layout shift), and lazy loading. Themes still using img_url miss out on these automatic optimisations, which directly affect Cumulative Layout Shift (CLS) and Largest Contentful Paint (LCP) - two Core Web Vitals that influence Google's page experience ranking signals.
What Causes It (Shopify-Specific)
Themes built before the 2022 image_url release
Themes released before Shopify introduced image_url (June 2022) used img_url as the standard filter. These themes were never updated to use the new filter, and since img_url still functions, the deprecation warning is easy to miss.
Copied Liquid snippets from older tutorials or docs
Developer documentation, YouTube tutorials, and community forums contain years of Liquid code examples using img_url. Developers copying these examples introduce the deprecated filter into custom themes.
Custom sections or snippets added without updating to new APIs
Stores that have added custom product sections, collection grids, or promotional banners using older Liquid patterns may be mixing new and old image filter usage within the same theme.
How to Detect It Manually
- 1In Shopify Admin → Online Store → Themes → Edit code, open your theme files
- 2Use the theme editor's search function to search for 'img_url' across all theme files
- 3Any result in a Liquid file (not a .json settings file) represents a usage that should be migrated
- 4Shopify's Theme Check linter (installed via Shopify CLI) also flags img_url usage with a deprecation warning
- 5Check your Shopify Theme Check output (npx shopify theme check) for LiquidFilter:DeprecatedFilter errors
How to Fix It (Step-by-Step)
Replace img_url with image_url in your Liquid
The syntax changes from a size string to width/height parameters.
{%- comment -%} Old - deprecated {%- endcomment -%}
<img src="{{ product.featured_image | img_url: '800x' }}" alt="{{ product.title }}">
{%- comment -%} New - use image_url with image_tag {%- endcomment -%}
{{- product.featured_image | image_url: width: 800 | image_tag:
alt: product.title,
loading: 'lazy',
width: product.featured_image.width,
height: product.featured_image.height
-}}Use image_tag for automatic srcset generation
The image_tag filter outputs a complete <img> element with srcset, width, height, and loading attributes. This prevents CLS by ensuring the browser knows the image dimensions before it loads.
{{- product.featured_image | image_url: width: 1200 | image_tag:
alt: product.featured_image.alt | default: product.title,
class: 'product-image',
loading: 'lazy',
widths: '375, 550, 750, 1100, 1500',
sizes: '(min-width: 1200px) 550px, (min-width: 750px) calc(100vw - 10rem), 100vw'
-}}Run Shopify Theme Check after migration
After updating all img_url references, run npx shopify theme check to confirm no remaining deprecation warnings. Also check any custom JSON template blocks that may reference image filters.
How SEOScan Detects This Issue
SEOScan inspects the rendered HTML output of product and collection pages, looking for img elements with Shopify CDN image URLs using the older size parameter format (e.g. _800x.jpg, _grande.jpg, _small.jpg suffixes) which are characteristic of img_url output. It also checks whether images are missing width and height attributes (a side-effect of img_url usage), which signals CLS risk. Pages with these patterns are reported alongside CLS score data.
Example Scan Result
Description
Page: /products/leather-wallet. 8 product images detected with Shopify CDN URLs using _800x.jpg size suffix format, characteristic of the deprecated img_url filter. None have explicit width and height attributes.
Impact
Images without explicit dimensions cause Cumulative Layout Shift (CLS) as the browser doesn't reserve space before loading. This contributes to a poor CLS Core Web Vitals score.
Recommended Fix
Migrate theme Liquid from | img_url: '800x' to | image_url: width: 800 | image_tag with explicit width and height attributes. Use Shopify Theme Check to find all usages.
Why It Matters for SEO
Core Web Vitals - CLS
img_url does not output width and height attributes, so the browser can't reserve space for images before they load, causing layout shift (CLS). image_url with image_tag auto-generates correct dimensions, preventing this shift.
Core Web Vitals - LCP
The image_url filter enables srcset generation via image_tag, allowing browsers to load the correct image size for the viewport rather than always loading an 800px image on a 375px mobile. This reduces LCP time on mobile, which is Google's primary Core Web Vitals measurement device.
Future Compatibility
While Shopify has not removed img_url, it's deprecated - meaning it won't receive performance improvements and could eventually be removed in a future Liquid version. Migrating now avoids emergency theme fixes later.
Real-World Validation Signals
- Shopify announced the img_url → image_url migration in their 2022 developer changelog, citing improved CDN performance and automatic responsive image support as primary benefits.
- Themes upgraded from img_url to image_url with image_tag consistently show reduced CLS scores in PageSpeed Insights, often moving from 'Needs Improvement' to 'Good' for CLS.
- Shopify's own Dawn theme was migrated to image_url in version 3.0 (2022), and all new theme submissions to the Shopify Theme Store are required to use image_url.
- Shopify Theme Check reports img_url as a deprecation warning in all linting runs, making it visible to any developer running theme validation.
When this may not need fixing
If your store uses a modern theme (Dawn 3.0+, or any theme purchased from the Theme Store after mid-2022) that already uses image_url throughout, there is nothing to fix. Also, if a theme developer or agency manages your theme and has already migrated, check Theme Check output before investing time here.
Frequently Asked Questions
Q: Will img_url stop working soon?
Shopify has deprecated img_url but not given a removal date. It continues to function. However, deprecated APIs in Shopify are eventually removed - Shopify typically gives 12–24 months notice. Migrating now is low-risk and improves performance immediately.
Q: Is this worth fixing if my CLS score is already good?
If your CLS score is already in the 'Good' range (below 0.1) and your theme happens to work around the missing dimensions via CSS aspect-ratio tricks, the urgency is low. However, migrating still future-proofs your theme and unlocks srcset for better LCP. Use Shopify Theme Check to quantify the number of remaining usages.
Q: What's the difference between image_url and img_url exactly?
img_url outputs just a URL string at a fixed size (e.g. product_800x.jpg). image_url outputs a URL but also enables the image_tag filter, which generates a complete <img> element with width, height, srcset, sizes, loading, and alt attributes - all the attributes required for performance best practices.
Q: Can I automate this migration across a large theme?
Shopify provides a migration guide in their developer documentation. For large themes, you can use find-and-replace across .liquid files, but each replacement requires checking the context (some img_url usages are in data attributes or schema JSON). Run Theme Check after each batch of changes.
Check Your Store for This Issue
SEOScan automatically detects shopify deprecated img_url filter: how to migrate to image_url and 4 related issues - with specific fixes for your store.
Run Free ScanRelated Issues
Render-Blocking Scripts on Shopify: Detection and Fixes
Performance · High
Shopify INP Score Poor: Apps Causing High Interaction to Next Paint
Performance · High
Shopify Cumulative Layout Shift from Images Missing Dimensions
Performance · Medium
Shopify OS 1.0 Theme Migration Debt: SEO Risks and What to Fix
Shopify-Specific · Medium