Shopware 6 — Remote Thumbnails
Starting with Shopware 6.6.4, Shopware supports remote thumbnail generation. Instead of creating physical thumbnail files on disk during media upload, Shopware generates thumbnail URLs that point to an external service — and smoxy can handle the actual resizing on the fly through its image manipulation feature.
This eliminates the need for pre-generated thumbnails entirely. No more bin/console media:generate-thumbnails, no wasted disk space, and instant support for any thumbnail size the storefront requests.
Disclaimer: This guide is based on the Shopware 6 developer documentation as of February 2026. Shopware may change the remote thumbnail feature, its configuration options, or the available pattern variables in future releases. Always refer to the official Shopware documentation for the most up-to-date information. smoxy cannot guarantee compatibility with future Shopware changes.
How It Works
Normally, Shopware generates physical thumbnail files (e.g., product_400x400.jpg, product_800x800.jpg) and stores them in the /thumbnail/ directory. With remote thumbnails enabled, Shopware skips this step and instead rewrites all thumbnail URLs to match a configurable pattern. That pattern can be set up to produce URLs that smoxy intercepts via a rewrite rule and processes on the fly.
The flow looks like this:
A visitor loads a product page in the storefront.
Shopware generates a thumbnail URL using the configured pattern (e.g.,
/thumbnail/800/media/ab/cd/product.jpg).The browser requests that URL from smoxy.
smoxy matches the URL against a rewrite rule and resizes the original image on the fly.
The processed image is delivered and cached by smoxy.
Prerequisites
Shopware 6.6.4 or later
smoxy's image manipulation feature
A configured rewrite rule in smoxy (see below)
Step 1: Configure Shopware
Edit the config/packages/shopware.yaml file in the Shopware installation and add the remote thumbnail configuration:
This tells Shopware to generate thumbnail URLs in the following format:
Available Pattern Variables
Shopware provides the following variables for the pattern:
{mediaUrl}
https://shop.example.com
Base URL of the media storage
{mediaPath}
media/ab/cd/ef/product.jpg
Relative path to the original image
{width}
800
Requested thumbnail width
{height}
800
Requested thumbnail height
{mediaUpdatedAt}
1716882050
Unix timestamp of the last media update (acts as cache buster)
Note: The ?ts={mediaUpdatedAt} query parameter does not affect the smoxy rewrite rule match but ensures that browsers and CDN caches serve fresh versions when an image is updated in Shopware.
Step 2: Create a Rewrite Rule in smoxy
In the smoxy dashboard, create a rewrite rule that catches the thumbnail URLs generated by Shopware and routes them through image manipulation.
Width Only (Recommended)
This is the simplest and most common setup. Shopware's default thumbnail sizes (400×400, 800×800, 1920×1920) are square, but the storefront srcset typically only varies by width with height auto-calculated to preserve the aspect ratio.
Shopware pattern:
smoxy rewrite rule:
Regex
^/thumbnail/(\d+)/(.*)
Target Path
/_sx/img/_/w:$1/q:80/plain/$2
A request to /thumbnail/800/media/ab/cd/ef/product.jpg?ts=1716882050 will:
Fetch the original image from
/media/ab/cd/ef/product.jpgon the origin server.Resize it to 800px width (height auto-calculated from the aspect ratio).
Set the output quality to 80%.
Deliver the processed image.
Width and Height
If both width and height need to be respected (e.g., for strictly sized grid layouts), the pattern can include both dimensions.
Shopware pattern:
smoxy rewrite rule:
Regex
^/thumbnail/(\d+)x(\d+)/(.*)
Target Path
/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3
Tip: Replace rs:fit with rs:fill if the image should completely fill the given dimensions (cropping excess) instead of fitting within them. See the resizing types reference for all available options.
Step 3: Clean Up Existing Thumbnails (Optional)
Once remote thumbnails are working, the existing physical thumbnail files on the server are no longer needed. They can be removed to free up disk space:
Important: Verify that remote thumbnails are working correctly in the storefront before deleting existing thumbnail files. Check the browser's developer tools (Network tab) to confirm that thumbnail requests are being served through smoxy.
Advanced Examples
Higher Quality for Large Images
Different quality levels can be applied based on the thumbnail size using two separate rewrite rules:
Rule 1 — Small thumbnails (low quality, fast loading):
Regex
^/thumbnail/small/(\d+)/(.*)
Target Path
/_sx/img/_/w:$1/q:60/plain/$2
Rule 2 — Large thumbnails (high quality):
Regex
^/thumbnail/large/(\d+)/(.*)
Target Path
/_sx/img/_/w:$1/q:90/sh:0.5/plain/$2
This requires two separate Shopware patterns (or a plugin that adjusts the pattern based on the thumbnail context).
Smart Cropping for Product Thumbnails
Use smart gravity to automatically focus on the most interesting part of the image when cropping:
Shopware pattern:
smoxy rewrite rule:
Regex
^/thumbnail/(\d+)x(\d+)/(.*)
Target Path
/_sx/img/_/rs:fill:$1:$2/g:sm/q:80/plain/$3
The g:sm (smart gravity) option ensures that product images are cropped around the most visually relevant area rather than always from the center.
Troubleshooting
Images Not Loading
Verify that the Shopware pattern produces URLs that match the smoxy rewrite rule regex. Open a product page, inspect an image in the browser, and check the generated
srcorsrcsetURL.Ensure the rewrite rule is active and positioned correctly in the smoxy rule list.
Wrong Image Dimensions
Check whether Shopware is passing
{width}only or both{width}and{height}— and make sure the rewrite rule regex matches accordingly.If images appear stretched, switch from
rs:forcetors:fitorrs:fill.
Stale Images After Update
The
{mediaUpdatedAt}timestamp in the query string should handle cache invalidation automatically. If stale images persist, a cache purge in smoxy may be necessary.
Further Reading
Last updated
Was this helpful?