PrestaShop Image Regeneration: When and How to Rebuild Thumbnails

How PrestaShop Handles Product Images

Every image uploaded to PrestaShop goes through a processing pipeline. When you add a product image, the system stores the original file and then generates multiple resized versions called thumbnails. Each thumbnail corresponds to an image type defined in the back office under Design > Image Settings. These image types specify exact pixel dimensions and are tied to specific contexts: product listings, product pages, cart previews, category headers, manufacturer logos, and more.

PrestaShop stores images in the /img/ directory. In PrestaShop 1.7 and 8.x, product images are organized using a directory structure based on the image ID. For example, an image with ID 1234 is stored at /img/p/1/2/3/4/. Inside that directory, you will find the original image (named by ID, like 1234.jpg) and all generated thumbnails (like 1234-home_default.jpg, 1234-large_default.jpg, 1234-small_default.jpg).

The naming convention follows the pattern: {image_id}-{image_type_name}.{extension}. This means every image type you define creates an additional file for every product image in your catalog. A store with 5,000 product images and 8 image types will have approximately 45,000 image files (5,000 originals plus 5,000 times 8 thumbnails). This scale matters when you need to regenerate them.

Understanding Image Types

Image types are defined in the database table ps_image_type and managed through the back office. Each image type has a name, width, height, and flags indicating which entity types it applies to (products, categories, manufacturers, suppliers, stores). The default PrestaShop installation includes several image types:

cart_default is typically 125x125 pixels, used in the shopping cart and mini cart. small_default is around 98x98 pixels, used in product listings on some themes. medium_default is around 452x452 pixels, used for product thumbnails on the product page. home_default is around 250x250 pixels, used on the homepage and category listings. large_default is around 800x800 pixels, used as the main product image on the product page.

Themes can define their own image type requirements. When you install a new theme, it typically registers its preferred image types during installation. The critical point is that the actual image files on disk must match what the theme expects. If the theme requests home_default at 340x340 but your image files were generated at 250x250 because you used a different theme previously, every product listing will display incorrectly sized images.

When Image Regeneration Is Necessary

Several situations require a full or partial thumbnail regeneration. Understanding when it is truly necessary saves you from running a process that can take hours on large catalogs.

Theme Change

This is the most common reason. Different themes require different image dimensions. When you switch from one theme to another, the new theme's templates reference image types with specific dimensions. If those dimensions do not match the existing thumbnail files, images appear stretched, cropped incorrectly, or blurry. After installing a new theme, always check its image type requirements and regenerate thumbnails to match.

Image Type Dimension Changes

If you modify the width or height of an existing image type through Design > Image Settings, the change only affects the database definition. All existing thumbnail files on disk retain their old dimensions. You must regenerate thumbnails for the modified image type to apply the new dimensions to existing images.

Adding a New Image Type

When you create a new image type, no thumbnail files exist for it yet. If a template references this new image type, it will display broken image links until you regenerate. The regeneration process creates the missing thumbnail files for every existing image.

Image Quality Issues

If you change the JPEG compression quality setting in PrestaShop (found in Performance > Image Settings or the image configuration section depending on your version), existing thumbnails were generated with the old quality setting. Regeneration applies the new quality level to all thumbnails.

After a Migration or Server Move

Sometimes during migration, thumbnail files get lost or corrupted while original images survive. If product images appear broken but originals exist in the expected directories, regeneration recreates all thumbnails from the originals.

Enabling WebP Format

PrestaShop 8.x introduced WebP support for product images. When you enable WebP generation, existing images do not automatically get WebP variants. You must regenerate thumbnails to create the .webp versions alongside the existing JPEG or PNG files.

Regeneration Through the Admin Panel

PrestaShop provides a built-in regeneration tool in the back office under Design > Image Settings (or Preferences > Images in older versions). At the bottom of the page, you will find the regeneration section.

Options Available

You can choose to erase previous images before regenerating. When enabled, PrestaShop deletes all existing thumbnails before creating new ones. This is useful when you want to remove thumbnails for image types that no longer exist, but it means all images will be unavailable during the regeneration process. When disabled, PrestaShop overwrites existing thumbnails and creates missing ones without deleting anything first.

You can select which entity types to regenerate: products, categories, manufacturers, suppliers, or stores. If you only changed product image dimensions, there is no need to regenerate category or manufacturer images.

Limitations of the Admin Panel Approach

The admin panel regeneration runs as a web request. This creates several problems for large catalogs. Web servers have execution time limits, typically 30 to 300 seconds depending on your configuration. A store with 10,000 product images and 8 image types needs to generate 80,000 thumbnail files. Even at a generous 10 images per second, that takes over two hours. Most web servers will terminate the process long before it finishes.

Memory limits also apply. Each image must be loaded into memory, resized using GD or ImageMagick, and saved. High-resolution original images can consume 20 to 50 MB of memory each during processing. PHP's default memory limit of 128 MB or 256 MB can be exhausted quickly, especially when processing images in sequence without proper memory cleanup.

If the process is interrupted by a timeout or memory error, you end up with a partially regenerated catalog. Some products have new thumbnails, others have old ones, and some might have none at all. This inconsistent state is worse than the original problem.

CLI Regeneration for Large Catalogs

For stores with more than a few hundred products, command-line regeneration is strongly recommended. It bypasses web server timeout limits and can be configured with higher memory limits.

Using the PrestaShop Console

PrestaShop 1.7.5 and later include a Symfony console. You can regenerate thumbnails using:

php bin/console prestashop:image:regenerate

This command accepts several options. To regenerate only specific image types, use the --image-type flag followed by the image type name. To process only products, categories, or other specific entity types, use the --entity flag. The --format flag lets you specify which output formats to generate (jpg, png, webp).

Run the command from your PrestaShop root directory. If you are using Docker, execute it inside the container:

docker exec -u www-data your-container php bin/console prestashop:image:regenerate

The -u www-data flag ensures generated files are owned by the web server user. Running as root creates files that the web server cannot serve or modify later.

Memory and Time Configuration

For CLI execution, you can increase PHP limits directly in the command:

php -d memory_limit=512M -d max_execution_time=0 bin/console prestashop:image:regenerate

Setting max_execution_time=0 removes the time limit entirely, and 512 MB of memory is sufficient for most catalogs. For stores with extremely high-resolution originals (4000x4000 pixels or larger), you may need 1 GB or more.

Custom Regeneration Approach

For very large catalogs (50,000 or more images), even the console command can be slow or problematic. A custom PHP approach lets you process images in batches with progress tracking, error handling, and the ability to resume after interruption.

The approach involves querying the database for all image records, iterating through them in batches of 100 or 200, generating thumbnails for each image, and logging progress. If the process is interrupted, you can resume from where it stopped by checking which thumbnails already exist.

A batch approach also allows you to spread the regeneration across multiple runs during off-peak hours, avoiding performance impact on the live store.

WebP Generation During Regeneration

WebP is a modern image format that provides significantly smaller file sizes than JPEG at comparable quality. PrestaShop 8.x can generate WebP versions of thumbnails during the regeneration process.

Enabling WebP Support

Before regenerating, enable WebP in your PrestaShop configuration. In PrestaShop 8.x, this option is in the image settings. When enabled, the regeneration process creates both the traditional JPEG/PNG thumbnail and a .webp version for each image type.

Server Requirements

WebP generation requires either the GD extension compiled with WebP support (--with-webp) or the ImageMagick extension with WebP delegates. You can check GD support with phpinfo() or gd_info(). Look for WebP Support in the output. If WebP support is missing, the regeneration process silently skips WebP creation without producing errors.

Disk Space Considerations

WebP files are typically 25 to 35 percent smaller than equivalent JPEG files, but you are storing both formats. A store with 40,000 JPEG thumbnails taking 2 GB of disk space will need approximately 3.4 GB total after WebP generation (the original 2 GB plus roughly 1.4 GB of WebP files). Plan your disk space accordingly before starting a full regeneration.

Serving WebP to Browsers

Generating WebP files is only half the solution. Your theme and server must be configured to serve WebP to browsers that support it while falling back to JPEG/PNG for browsers that do not. This is typically handled through <picture> elements in the theme templates or through server-side content negotiation using the Accept header.

In Apache, you can add rewrite rules that check for WebP support and serve the WebP version when available. In Nginx, the try_files directive can check for a .webp version of the requested image and serve it if the browser's Accept header includes image/webp.

Performance Impact and Mitigation

Image regeneration is CPU-intensive and I/O-heavy. On a live store, it can degrade performance significantly if not managed carefully.

CPU Impact

Each image resize operation requires loading the original into memory, performing the resize algorithm, applying any quality/compression settings, and writing the result to disk. The resize operation itself is computationally expensive, especially for large images being scaled down to small thumbnails. On a shared hosting environment, this can saturate the CPU and slow down the entire store.

I/O Impact

Regeneration reads every original image and writes multiple thumbnail files. On traditional hard drives, this creates significant I/O load. On SSD storage, the impact is much lower but still noticeable at scale. The I/O pattern is particularly unfriendly to spinning disks because it involves random reads (originals scattered across directories) combined with sequential writes (thumbnails in the same directories).

Running Regeneration During Off-Peak Hours

Schedule regeneration for your lowest-traffic period. For European stores, this is typically between 2 AM and 6 AM. For stores with global traffic, there may not be a true off-peak, but you can identify relative low points from your analytics data.

Using Nice and Ionice

On Linux servers, you can reduce the priority of the regeneration process so it does not starve other processes of resources. The nice command lowers CPU priority, and ionice lowers I/O priority:

nice -n 19 ionice -c 3 php bin/console prestashop:image:regenerate

A nice value of 19 is the lowest priority. Ionice class 3 is the idle class, meaning the process only gets I/O time when nothing else needs it. This dramatically reduces the impact on the live store but makes the regeneration take longer.

Temporary Scaling

If you are on a cloud server, consider temporarily scaling up your server (more CPU cores, more RAM, faster storage) for the duration of the regeneration, then scaling back down. The extra cost for a few hours of higher-tier resources is usually minimal compared to the impact of a slow, multi-day regeneration on your store's performance.

Avoiding Timeouts During Regeneration

Timeouts are the most common problem with image regeneration. Here are the specific settings and configurations that prevent them.

PHP Configuration

The max_execution_time directive limits how long a PHP process can run. For CLI execution, this is typically already set to 0 (unlimited), but verify by checking php -i | grep max_execution_time. For web-based regeneration through the admin panel, increase this value in your php.ini or .htaccess:

php_value max_execution_time 7200

Also increase max_input_time if you are using the admin panel, as the form submission timeout is separate from execution timeout:

php_value max_input_time 7200

Web Server Timeout

Apache's Timeout directive and Nginx's proxy_read_timeout / fastcgi_read_timeout can terminate long-running requests even if PHP itself has not timed out. For Apache: Timeout 7200. For Nginx, add to your server block: fastcgi_read_timeout 7200; or proxy_read_timeout 7200;.

PHP-FPM Configuration

If you use PHP-FPM (which most modern setups do), the request_terminate_timeout in your pool configuration can also kill long-running processes. Set it to 0 to disable the timeout, or match it to your desired maximum runtime:

request_terminate_timeout = 7200

Cloudflare and CDN Timeouts

If your store is behind Cloudflare or another CDN, the CDN has its own request timeout (Cloudflare's free plan has a 100-second timeout). This makes admin panel regeneration effectively impossible behind a CDN. You must either use CLI regeneration, bypass the CDN for admin access, or use a solution that processes images asynchronously.

Incremental Regeneration Strategies

Full regeneration processes every image in the catalog. For stores with tens of thousands of images, this can take many hours. Incremental approaches process only the images that actually need new thumbnails.

Selective Image Type Regeneration

If you only added or modified one image type, you do not need to regenerate all image types. Use the --image-type option in the console command to target only the specific image type that changed. This reduces the work to one-eighth (or whatever fraction of your total image types) of a full regeneration.

Date-Based Processing

If you need to regenerate thumbnails for recently added products only (for example, after fixing an image processing issue), you can query the database for images added after a specific date and process only those. The ps_image table does not have a date column by default, but the associated ps_product table has date_add and date_upd fields that can be used to identify recently modified products.

Missing Thumbnail Detection

Instead of regenerating everything, scan the image directories to find images that are missing specific thumbnails and only regenerate those. This is the fastest approach when you have added a new image type or when a partial regeneration was interrupted.

The logic is straightforward: for each image ID in the database, check if the expected thumbnail file exists on disk. If it does not, regenerate just that thumbnail. This turns a multi-hour full regeneration into a targeted process that might take minutes.

Parallel Processing

For very large catalogs, you can split the image ID range into chunks and process them in parallel using multiple PHP processes. For example, one process handles image IDs 1 through 10000, another handles 10001 through 20000, and so on. Each process runs independently, and the combined throughput is roughly proportional to the number of parallel processes (limited by CPU cores and I/O bandwidth).

Be careful with parallel processing and disk I/O. Running too many processes simultaneously on a traditional hard drive will cause I/O contention and actually slow things down. On SSD storage, 4 to 8 parallel processes typically work well.

Image Format Considerations

PrestaShop supports JPEG, PNG, and GIF as source formats, and can generate thumbnails in these formats plus WebP. The source format affects regeneration behavior.

JPEG Images

JPEG is the most common format for product photos. It supports lossy compression, which means each time a JPEG is saved, some quality is lost. This is why regenerating thumbnails from original uploads produces better results than regenerating from previously resized thumbnails. Always ensure you are working from the original uploaded image, not a previously generated thumbnail.

PNG Images

PNG supports transparency and lossless compression. If your product images use transparent backgrounds, PNG thumbnails preserve that transparency. However, PNG files are typically much larger than JPEG files. Consider whether you actually need transparency. If not, converting PNG product images to JPEG during regeneration can significantly reduce disk space and improve page load times.

GIF Handling

PrestaShop can accept GIF uploads, but generated thumbnails from GIF sources are static (no animation preserved). If you have animated GIF product images, be aware that regeneration produces static thumbnails from the first frame.

Post-Regeneration Verification

After regeneration completes, verify the results before assuming everything is correct.

Spot-Check Image Quality

Open several product pages and inspect the images visually. Check that thumbnails are sharp, correctly proportioned, and not stretched or pixelated. Pay special attention to images that were originally small (close to or smaller than the thumbnail dimensions), as these are most likely to show quality issues when upscaled.

File Count Verification

Compare the number of generated thumbnails against expectations. If you have 5,000 product images and 8 image types, you should have approximately 40,000 thumbnail files (plus the originals and potentially WebP variants). A significantly lower count indicates that the regeneration process was interrupted or encountered errors on some images.

File Permission Check

Verify that regenerated files are owned by the web server user (typically www-data on Debian/Ubuntu or apache on CentOS). If you ran the regeneration as root, the files may not be readable by the web server, causing broken images on the frontend. Fix with: chown -R www-data:www-data img/p/.

Cache Clearing

After regeneration, clear all caches. This includes PrestaShop's internal cache (Advanced Parameters > Performance), any opcode cache (OPcache), and any CDN or reverse proxy cache. Old cached pages may still reference old image URLs or dimensions. If you use a module that generates CSS sprites or inline images, regenerate those as well.

If your store is behind Cloudflare, purge the cache for the /img/ path or do a full cache purge. Cloudflare caches images aggressively, and visitors may see old thumbnails until the CDN cache expires or is purged.

Troubleshooting Common Regeneration Problems

Black or Corrupted Thumbnails

This usually indicates a GD library issue. The GD extension may not support the source format (for example, GD compiled without JPEG support). Verify GD capabilities with gd_info(). Another cause is insufficient memory: if PHP cannot allocate enough memory to load the original image, GD may produce a black image instead of throwing an error.

Wrong Dimensions in Generated Thumbnails

If thumbnails have unexpected dimensions, check the image type definitions in the database. The admin panel may show one value while the database contains another (this can happen after a failed import or manual database modification). Query directly: SELECT * FROM ps_image_type WHERE name = 'home_default';

Regeneration Hangs Without Progress

A hung regeneration process usually means it encountered a very large image that exhausted available memory. Check the PHP error log for memory allocation failures. The solution is to increase the memory limit or pre-process the problematic source images to reduce their resolution before regeneration.

Permission Denied Errors

If regeneration reports permission errors, the PHP process cannot write to the image directories. This commonly happens in Docker environments where bind-mounted volumes have different ownership inside and outside the container. Ensure the user running the regeneration command has write access to the entire /img/ directory tree.

Summary

Image regeneration is a maintenance task that every PrestaShop store owner encounters, usually during a theme change or when optimizing image settings. For small catalogs (under 500 products), the admin panel tool works adequately. For anything larger, CLI regeneration is the only reliable approach. The key principles are: always work from original images, match your image type definitions to your theme's requirements, manage server resources and timeouts proactively, use incremental approaches when possible, and verify results after the process completes. With WebP becoming the standard for web images, regeneration also serves as the mechanism to create modern format variants of your entire product catalog, delivering smaller file sizes and faster page loads to your customers.

For more details, read our guides: Image Optimization for PrestaShop: Faster Loading Without Losing Quality and PrestaShop Image Optimization: Alt Tags, Lazy Loading and Page Speed.