A product photograph in WooCommerce is not one file. The shop grid loads one version of it, the product page loads a larger one, and the strip of gallery thumbnails under the main image loads a third. Three files, three registered sizes, three separate decisions that were probably made for you by a theme you have never looked inside.
Most stores never open the panel where those decisions live. The ones that do usually change a number, save, reload the shop page, and see exactly what they saw before. That is not a broken install. It is the mechanism working as designed, and it catches almost everybody once.
The sizing half of this matters because of the photography half. If sixty products are shot with the same light, the same background and the same margin, and the catalogue then crops them three different ways, the consistency you paid for never reaches the customer.
The three sizes behind one product photograph
WooCommerce registers three image sizes of its own, on top of the ones WordPress already registers for every upload. They have real slugs and you will see them in theme code and in support threads.
woocommerce_thumbnailis the catalogue image. It appears in the product grids: the shop page, category archives, related products, upsells. WooCommerce documents a default of 300 pixels wide, square cropped.woocommerce_singleis the main image on a single product page. WooCommerce documents a default of 600 pixels wide, uncropped, so the aspect ratio of what you uploaded survives.woocommerce_gallery_thumbnailis the row of small images below the main one, the ones a customer clicks to switch the gallery. It is always square cropped, with a documented default of 100 by 100.
Those three sit on top of the sizes WordPress registers for every upload, which is why a product image writes noticeably more files to disk than a blog image does. If the idea that one upload becomes many files is new to you, that is the piece to read first, because everything below depends on it.
The settings live at Appearance > Customize > WooCommerce > Product Images. That panel is where you set the catalogue and thumbnail widths and, more importantly, the cropping behaviour. WooCommerce puts these controls in the Customizer rather than on its own settings screen, and there is no field for them on the product edit page, which is why people hunt for a while before finding them.
The cropping choice is the one that matters
WooCommerce offers three cropping options, and the documentation describes them plainly. 1:1 makes all images appear as squares. Custom lets you enter a ratio of your own. Uncropped shows images as they are, and the documentation adds its own warning that this “can result in images appearing non uniformly”.
That warning is doing a lot of work. Imagine a range where some products were shot portrait because they are tall and some landscape because they are wide, which is what happens when nobody wrote a rule. Here is what each setting does to that range.
Uncropped keeps every photograph honest and makes the grid ragged. Cards end up different heights, rows stop lining up, and the empty space around each product varies from card to card. Some themes paper over this with a fixed-height container, which just moves the inconsistency into the whitespace instead of the outline.
1:1 gives you a clean grid and takes a centre crop to get there. A tall bottle loses its cap and its base. A wide keyboard loses both ends. If the original photographs already have generous margin around the product, this is harmless and it is the right default. If they are tightly framed, square cropping quietly amputates the range.
Custom is the honest middle. Pick one house ratio, say 4:5, and every catalogue image is cropped to it. The crop risk is the same as 1:1, but at least the ratio is a decision you made rather than one you inherited.
There is a second-order effect that confuses shoppers more than store owners realise. Because woocommerce_thumbnail is square cropped by default and woocommerce_single is uncropped by default, the same photograph is cropped in the grid and uncropped on the product page. A customer clicks a neat square and lands on a tall picture with more of the product visible. It reads as the wrong image. The fix is upstream rather than in the settings: shoot to one ratio with margin, so cropping has nothing to cut.
Why changing a size does nothing until you regenerate
Registered image sizes are instructions for one moment: the moment a file is uploaded. WordPress reads the list of registered sizes, writes one derivative file per size, and records each one in the attachment’s metadata. Changing a number afterwards changes the instruction for the next upload. It does not go back and rewrite anything that already exists.
What happens on the front end is worth understanding precisely, because it explains why the grid still looks fine. When a template asks for woocommerce_thumbnail and no file of that size is recorded for the attachment, image_downsize() in wp-includes/media.php finds no intermediate size, keeps the plain attachment URL and reads the dimensions straight from the attachment metadata. The browser is handed the full-size file and CSS scales it down. The layout looks unchanged. The page weight is not.
How bad that is depends on what “full” means on your site. WordPress scales oversized uploads down and keeps the result as the full size, writing a -scaled file, with the threshold defaulting to 2560 pixels on the longest side through the big_image_size_threshold filter. So a category page that should be serving thirty files 300 pixels wide can quietly be serving thirty files up to 2560 pixels wide instead, on mobile, over a phone connection.
WooCommerce handles this with regeneration. It documents two events that trigger it: publishing settings in the Customizer, and switching themes. When it detects either, it queues a background regeneration job. You can watch that job under WooCommerce > Status > Logs by choosing the wc-background-regeneration log, and you can start one deliberately from WooCommerce > Status > Tools using Regenerate shop thumbnails.
On a small shop this finishes while you are still reading the changelog. On a large catalogue it is a real job. Every attachment has to be decoded into memory, resized and re-encoded once per changed size, and product photography is usually the heaviest imagery on a site. A store with 2,000 products and three gallery images each is 6,000 originals, and each changed size means 6,000 more encode operations. Peak memory per image tracks pixel dimensions rather than file size, so a modest 4 MB JPEG at 6000 by 4000 is a bigger problem than its file size suggests. On shared hosting, workers get killed partway and the job crawls.
If you would rather regeneration never started on its own, WooCommerce documents a filter for exactly that. Disabling the automatic job and running the tool by hand at a quiet hour is a reasonable trade on a big store.
// Stop WooCommerce queueing thumbnail regeneration by itself.
// Run WooCommerce > Status > Tools > Regenerate shop thumbnails when you choose to.
add_filter( 'woocommerce_background_image_regeneration', '__return_false' );One thing regeneration does not do is tidy up after you. A size you stop using is simply no longer generated for new uploads; the files already written for it stay exactly where they are. Change your catalogue width three times over two years and the uploads folder carries all three generations. That is a large part of why store media libraries grow faster than anyone expects, and it is worth doing a proper clean-up pass before you start a regeneration run rather than after, so you are not re-encoding files no product still points at.
Blurry catalogue images
This is the most common product image complaint and it has a mechanical cause. The theme renders a catalogue card wider than the registered thumbnail size, so the browser takes a 300 pixel file and stretches it across 400 pixels of layout. Upscaling invents detail that was never captured, and the result is soft edges and mushy text on packaging.
WooCommerce says the same thing in its own troubleshooting notes: blurry product images are usually caused by theme styling that specifies image dimensions incompatible with the uploaded images. Its guidance is to keep originals at a minimum of 800 by 800 for most themes, and to set thumbnails to double the size the theme renders when you care about high-density displays, because a card rendered at 400 CSS pixels needs 800 device pixels on a 2x screen.
The check takes a minute. Open a category page, inspect one product image in the browser, and read the width the element is actually rendered at. Then look at the file the src points to and read its width from the filename suffix. If the rendered box is wider than the file, that is your answer, and the fix is to raise the registered thumbnail width to at least the rendered width (twice it, if you want it sharp on a retina laptop) and then regenerate. There are several other causes of blurry images in WordPress, each with its own tell, but on a WooCommerce grid this one is nearly always it.
Whether your catalogue images are big enough is arithmetic, not opinion, and it depends on the layout as much as on the settings.
Put the three settings in below along with your content width, your column count and your gutter. It works out the width a thumbnail is actually displayed at, doubles it for a retina screen, and compares that with what you have configured. Then it lists every file the shop will write for one product photograph and what that comes to across the whole catalogue.
WooCommerce image size planner
WooCommerce builds every product image from three settings. Give the planner your shop layout as well and it works out the width each image really needs, the files WordPress writes for a single upload, and what that adds up to across the catalogue. Everything is worked out in this browser tab, nothing is uploaded and nothing leaves the page.
woocommerce_
Measure the content area, not the browser window: it is the width the product grid actually gets on a desktop. The main image usually takes about half of it on the product page.
The gallery counts too: one main image and four gallery images is five uploads per product.
woocommerce_single_image_width
woocommerce_thumbnail_image_width
woocommerce_thumbnail_cropping
| Size | Registered | File on disk | Estimate |
|---|
A registered height of 0 is not a mistake: it means the height is free, so only the width is enforced and the photo keeps its own ratio. File sizes are estimated at a quarter of a byte per pixel, which is roughly what a photograph costs as a JPEG at the WordPress default quality. Your files will differ, the pattern will not.
A new setting only applies to uploads that arrive after it. Everything already in the library keeps the files it was given on the day it was uploaded, so the sizes have to be built again:
wp media regenerate --only-missing=false --yes
On a shop of this size that rewrites every file in one long run and hammers the disk while it does. Take a copy of the uploads folder first, run it out of trading hours, and never on a live shop in the middle of the day.
If the values belong in a small plugin rather than in the Customizer, filter them. The snippet carries the recommended widths from above.
Themes can override all of this
Since WooCommerce 3.3 a theme is allowed to declare the three widths itself, through add_theme_support(), and many commercial WooCommerce themes do exactly that because their layouts were designed around specific numbers.
add_action( 'after_setup_theme', function () {
add_theme_support( 'woocommerce', array(
'thumbnail_image_width' => 400,
'single_image_width' => 800,
'gallery_thumbnail_image_width' => 150,
) );
} );When a theme declares sizes this way, WooCommerce documents that the top section of the Customizer panel is hidden and only the cropping option remains visible. Store owners keep control of aspect ratio and cropping, and lose control of the widths.
That single behaviour explains an entire genre of support ticket. Someone follows a tutorial, reaches the step that says set the catalogue image width, and the field is not there. Nothing is broken and nothing needs reinstalling. The theme decided. If you need different numbers, override the declaration rather than editing the parent theme, which means putting it in a child theme so the next theme update does not undo your work.
The specification comes before the camera
Now the other half, which decides whether the cropping settings above are painless or destructive. Open almost any small shop and scroll the category page. Some products are on white, some on a wooden table, one has a shadow and one is floating, two are slightly warmer than the rest, and one is a manufacturer photo with a watermark in the corner.
Every individual picture is fine. Together they look like a jumble sale, and the reason is not photography. It is that nobody ever wrote down what a product picture on this shop is. That takes ten minutes and pays for itself immediately. Decide, once:
- The canvas. Square is the safe default because grids, thumbnails and marketplaces all like it, and because it survives a 1:1 crop untouched. Pick one ratio and never deviate.
- The margin. How much empty space around the product, as a percentage of the canvas rather than in pixels. Something like ten per cent. This is the single biggest driver of whether a grid looks calm, and it is also your insurance against cropping.
- The background. One color, one gradient, or one surface. Not three.
- The shadow. Present or absent, and if present, always the same direction and softness.
- The angle. Straight on, three quarter, or from above, consistently.
The margin rule is the one people skip and it matters more than the background. If one product fills its frame and the next sits small in the middle, the grid looks broken even when both are on identical white. Scale each product so it occupies roughly the same proportion of its canvas and half the problem disappears. It also means that when WooCommerce takes its centre crop, there is nothing important near the edges to lose.
Cutting out without the tell-tale halo
If you are putting products on a consistent background, you have to separate them from whatever they were shot on. Three things specific to products are worth saying.
Subject detection is very good at products. Manufactured objects have clear boundaries and automatic detection handles them well. Select the subject, turn the selection into a mask rather than deleting anything, and you are most of the way there with a step you can still undo.
Refine the edge before you judge it. A cut-out looks perfect against the old background and reveals every flaw against the new one. Put it on the final background first, then look at the edge.
Glass, chrome and anything transparent will fight you. These need the reflections and the see-through parts kept, which no automatic mask does well. Either shoot them on the background you actually want, or budget real time for them.
The shadow is what sells it
A cut-out product with no shadow floats. It reads as a sticker, and the eye files it as artificial without ever articulating why.
A believable contact shadow follows three rules. It is darkest and sharpest right where the object touches the surface, and it gets lighter and softer as it moves away. It goes in the direction the light is not. And it is never pure black, it is a dark version of the surface color, because a shadow is a surface with less light on it rather than a black shape lying on top.
Get those three right and a flat cut-out sits on a table. Get them wrong and no amount of gradient will help. If the product was photographed with a real shadow, keep it and mask it back in at reduced opacity. Real shadows have a subtlety that is genuinely hard to fake.
Consistency is a settings problem, not a talent problem
The good news is that this is exactly the kind of repetitive precision software is better at than people. Work out the sequence once on a single image: the resize, the background, the adjustment, the sharpening, the export. Then apply that same sequence to the whole set, writing new attachments rather than overwriting originals, so every picture in the range gets literally the same treatment.
Not similar treatment. The same. That is the thing you cannot achieve by eye across sixty products on a Tuesday afternoon, no matter how careful you are, and it is the whole reason batch processing exists.
If you want to do that inside WordPress rather than in a separate application, WunderPaint Pro’s Image Processor resizes, converts and re-encodes a whole selection in one pass, with output as new attachments or versioned overwrites.
The same run should settle the export decisions too: the format, the encoder quality, the maximum dimension. Do that once for the set and your product images are consistent not only in appearance but in file size, which the store’s page speed will notice. It also means the originals you feed WooCommerce are predictable, so when regeneration runs, every product produces derivatives of a similar weight instead of a handful of 4 MB outliers dragging category pages down.
The detail shot nobody takes
One last thing, and it is not about consistency at all. Buyers zoom. Not on every product, but on the ones they are seriously considering, and what they are looking for is texture: the weave, the grain, the seam, the finish. A single close-up at full resolution answers questions that three more catalogue shots do not, and it is the picture most small shops never take.
This is also where the single product width earns its keep. Themes that offer a zoom or a lightbox on the product page need a file with pixels to spare, which is why WooCommerce’s own advice to keep originals at 800 by 800 or larger is a floor rather than a target. The image can render small on screen and still need to be large in the file.
Symptom and cause
The grid has ragged rows and cards of different heights. Cropping is set to uncropped and the range mixes portrait and landscape originals. Choose 1:1 or a custom ratio, or reshoot the outliers to the house ratio.
You changed a width, published, and nothing changed. Existing attachments still have no file at the new size, so the front end falls back to the full-size original. Regeneration has to run before anything is different.
The setting everyone writes about is not in your Customizer. The theme declares widths through add_theme_support(), so WooCommerce hides that section and leaves only the cropping control. Override it from a child theme if you need different numbers.
Catalogue images look soft on a laptop but fine on a phone. The theme renders the card wider than the registered thumbnail width, or the screen is a 2x display and the file has half the pixels it needs. Measure the rendered width, then set the registered width to match or double it.
One product looks zoomed in compared to the rest. It was photographed closer than the others, so square cropping cut away the little margin it had. This is a photography rule that was never written down, not a settings problem.
The shop got slower after a redesign. The new theme declared different widths, regeneration was queued but never finished, and a proportion of products are still serving full-size originals into small grid cards. Check the regeneration log before you blame the theme.
Where this leaves you
The three WooCommerce sizes are not complicated once you accept what they are: instructions applied at upload time, not display rules applied at render time. Set the catalogue width to at least the width your theme renders a card at, leave the single product image generous enough to reward a zoom, pick one cropping behaviour and stop changing it. Then regenerate once, deliberately, at a time when a slow site does not cost you anything.
The cropping option is the setting that decides whether your store looks designed or assembled, and it is the one that is least about WooCommerce. Square cropping is only kind to photographs that were framed with margin. Uncropped is only kind to ranges that were shot to one ratio. Whichever you choose, the setting is downstream of a decision somebody made with a camera, which is why the ten minute specification is worth more than an afternoon of adjusting numbers in the Customizer.
Keep the set consistent, keep the framing calm, keep the shadows honest, give the crop something to spare at the edges, and then give people one picture where they can see what the thing is actually made of. That combination does more for trust than any amount of retouching, and it makes every sizing decision afterwards a formality instead of a rescue operation.
