Migrating product images when upgrading to Magento 2: Step-by-step guide

When upgrading from Magento 1 to Magento 2, product images are just as important as products and customer data. These images are tied to your product presentation, user experience, and sales, so missing or broken images after migration can hurt your store’s performance.

Migrating product images involves more than moving files; you also need to ensure image paths are correctly linked in Magento 2’s database. This guide walks you through preparing your environments, transferring files, mapping paths, and verifying results to keep your storefront looking flawless after the upgrade.

Step 1: Prepare and understand magento image storage before migration

Before starting the product image migration process, it is crucial to create a secure foundation. This step ensures that you avoid data loss, broken product galleries, or missing image references after upgrading. It involves understanding how Magento stores product images and preparing both your source and destination environments.

1. Understand Magento product image storage structure

Knowing how Magento organizes and references images will help you migrate them without breaking product associations.

+ Magento 1 Image storage: In Magento 1, product images are stored in the media/catalog/product directory. Inside this, Magento creates multiple subfolders that are automatically named based on the first two characters of the image filename. For example, a file called myproduct.jpg would be placed in the /m/y/ subfolder.

+ Magento 2 Image storage: In Magento 2, the naming convention for these subfolders remains the same, but the directory structure changes slightly. Images are stored inside the pub folder for better separation of public assets, meaning the full path becomes pub/media/catalog/product.

Database linkage:

Magento does not store the actual image files in the database. Instead, it keeps references to each image — such as the file path and name — and links them to the corresponding product SKU.

These references are primarily stored in the catalog_product_entity_media_gallery table, while other related tables define additional details such as image labels, display positions, and assigned roles (e.g., base image, thumbnail, or small image).

Understanding this relationship between the file system and the database is essential for a smooth migration.

2. Prepare your Magento 2 environments

Taking proper precautions before migration will greatly reduce the risk of losing valuable product visuals.

+ Backup your media directory: Use FTP, SSH, or your hosting file manager to download this directory to a secure location on your local computer or cloud storage. This ensures you have a secure copy in case anything goes wrong during the migration.

+ Backup your Magento database: Back up your Magento database to safeguard product records and image references in case something goes wrong. This can be done using phpMyAdmin from your hosting control panel or by running the mysqldump command via SSH: mysqldump -u username -p database_name > backup.sql

3. Confirm access to both source and destination servers

Confirm you have all the necessary access credentials before starting the migration:

+ SSH or FTP credentials for both your old store (source) and your new Magento 2 store (destination).

+ Sufficient permissions to read, write, and modify files in the media directories.

+ Access to the Magento admin panel for both environments to verify configurations and perform database synchronization if needed.

By combining a solid understanding of Magento’s image storage system with complete backups and verified access, you will minimize migration risks. Skipping this step could lead to broken product galleries, missing images, and potentially hours of recovery work after the upgrade.

Step 2: Synchronize media storage in Magento 1

Before running the migration, confirm that your Magento 1 database contains the most up-to-date image references. If your store stores media paths in the database (instead of or in addition to the filesystem), you should synchronize them first.

Steps:

+ Log in to your Magento 1 Admin Panel.

+ Go to System > Configuration > ADVANCED > System.

+ In the Storage Configuration for Media section, select Media Storage Database.

+ Click Synchronize to update and sync all media file references between the file system and the database.

This step ensures that any recently uploaded product images or changed file paths are recorded in the database before you migrate.

Step 3: 2 Ways to transfer media files to Magento 2

Once your environments are prepared and backups are secured, the next step is to transfer your product image files from the old Magento installation to the new one. Magento product images must be placed in the exact directory structure expected by the new store, so maintaining the folder hierarchy during transfer is essential to prevent broken image references.

Your goal: copy all contents of the product folder from Magento 1 (media/catalog/product) to the correct destination path in Magento 2 (pub/media/catalog/product) while preserving the original folder structure.

There are two primary methods you can use: zipping and unzipping the folder or performing a direct file transfer.

Method 1: Zipping and Unzipping (Recommended for faster transfer)

This method is ideal if you have a large number of product images and want to move them quickly while minimizing the risk of file corruption during transfer.

Requirements: Enough disk space to create a temporary compressed file; SSH/SFTP or hosting file manager access.

+ Navigate to the Magento 1 media directory: Go to media/catalog/product in your old Magento installation.

+ Compress the folder: Create a .zip file containing all subfolders and images. This speeds up the transfer and reduces the risk of file corruption.

+ Upload to the Magento 2 server: Transfer the .zip file to the pub/media/catalog/product directory in your Magento 2 installation using FTP, SSH, or your hosting file manager.

+ Unzip in place: Extract the .zip file inside the target directory, ensuring the subfolder structure remains intact so Magento can correctly match images with database references.

Method 2: Direct file transfer

If you prefer not to compress your files, you can copy them directly from the old store to the new store.

+ Connect to both servers: Use FTP, SSH, scp, or rsync to connect to your old and new servers.

+ Locate the source directory: On the old store, go to media/catalog/product.

+ Copy files directly: Transfer all files and subfolders to pub/media/catalog/product on the new Magento 2 store.

While this method can be simpler for smaller sets of images, it can take longer for large collections and may be more prone to transfer interruptions. If using FTP, ensure your connection is stable and that your client is configured to resume interrupted transfers automatically to avoid missing files.

Step 4: Mapping image paths

To ensure product images display correctly after migration, you need to map image paths to Magento 2 using the Magento Data Migration Tool.

Steps:

+ Run the Magento Data Migration Tool to migrate product, category, customer, and order data from Magento 1 to Magento 2.

+ During migration, the tool does not physically copy images, but it will transfer and adjust image path references from the Magento 1 database so that they match the Magento 2 directory structure.

+ Confirm that your migration configuration includes the catalog_product_entity_media_gallery table, as this table stores all image metadata such as file paths, labels, and roles.

+ After running the tool, Magento 2 should correctly point to the copied image files in pub/media/catalog/product that you transferred earlier.

Step 5. Clear cache and reindex

Run the following CLI commands on your Magento 2 server to refresh URLs, rebuild indexes, and ensure image references are up to date:

bash

php bin/magento cache:clean

php bin/magento cache:flush

php bin/magento indexer:reindex

Step 6. Test on the frontend

+ Visit multiple product pages on the frontend to verify that images display correctly.

+ Check all image roles — Base Image, Small Image, and Thumbnail — for accuracy and consistency.

+ If certain images are missing, review both the file system and database references for mismatches.

Want to take your storefront’s visuals even further? Check out our guide on Improving Customer Experience on Magento Product Pages for practical tips to boost engagement and conversions.

Step 7. Post-migration: Optimize images to improve loading speed

Once your product images are successfully migrated to Magento 2, the work doesn’t end there. Unoptimized images can slow down page load times, hurt SEO rankings, and create a poor user experience, especially for mobile shoppers. Post-migration optimization ensures that your new Magento 2 store benefits from faster performance, better search engine visibility, and an improved shopping experience.

Configure auto-resize in Magento 2 backend

You can set Magento to automatically resize large, oversized images before they are displayed on product pages.

Steps to access and configure image upload settings:

+ In the Magento Admin panel, navigate to Stores > Settings > Configuration.

+ In the left panel, expand Advanced and select System.

+ Expand the Images Upload Configuration section.

+ Deselect the Use system value checkbox for the settings you want to customize.

+ Adjust the options as needed:

Enable Frontend Resize – Resizes large images automatically.

Quality – Controls JPEG/PNG quality after resizing.

Maximum Width – Sets the maximum allowed width in pixels.

Maximum Height – Sets the maximum allowed height in pixels.

+ Click Save Config to apply the changes.

Result: Magento will automatically resize oversized product images, reducing their display size and improving page speed.

Note: Magento’s built-in image settings are limited in scope, as they only resize images to fit the defined dimensions without performing any compression to reduce file size. Additionally, these settings cannot convert images into more efficient formats such as WebP, which are designed to deliver faster loading times while maintaining visual quality.

Convert images to a modern format for faster loading

For additional performance gains, convert your product images into the WebP or AVIF format. This format significantly reduces file size without noticeable quality loss.

+ AVIF: Even more efficient than WebP but with limited browser support (still growing).

+ WebP: Supported by most modern browsers, offers ~25–35% smaller file sizes than JPEG/PNG at similar quality. Recommended option: WebP Image Extension for Magento by BSS Commerce — a trusted Magento 2 extensions provider. This tool automatically converts uploaded images to WebP, helping you deliver lighter, faster-loading pages without manual editing. Check it out now.

+ Keep JPEG or PNG fallbacks for older browsers if you use WebP or AVIF.

Responsive image setup

Mobile users account for a large percentage of eCommerce traffic, and serving oversized desktop images to mobile devices wastes bandwidth and slows load times.

How to set it up in Magento 2:

+ Leverage Magento 2’s built-in responsive image capabilities: In your theme’s templates, use the srcset and sizes attributes in <img> tags to deliver different image versions depending on screen width.

html

<img

src="image-800.jpg"

srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"

sizes="(max-width: 600px) 400px, (max-width: 992px) 800px, 1200px"

alt="Sample Product"

>

+ Use different image roles for thumbnails, small images, and base images. This prevents oversized images from being loaded in preview or category grids.

Implementing a CDN service

A Content Delivery Network (CDN) stores copies of your images in multiple server locations worldwide and delivers them to customers from the nearest node.

How to integrate a CDN in Magento 2:

+ Choose a CDN provider: Cloudflare, AWS CloudFront, Fastly (used by Magento Commerce), KeyCDN.

+ Configure in Magento 2 Admin

Go to Stores > Configuration > Web > Base URLs (Secure/Unsecure)

Update Base URL for User Media Files to your CDN URL (e.g., https://cdn.yourstore.com/).

+ Purge and sync: After setting up, clear Magento cache and CDN cache to ensure the latest optimized images are delivered.

Extra tip: Some CDNs also offer on-the-fly image optimization (automatic WebP conversion, resizing, and compression) without manual processing.

Faster images are just one part of the equation. Learn how to optimize your entire category listing with our Magento 2 Category Page Speed Optimization Best Practices guide.

Updating ALT tags for SEO

During migration, alt tags and image metadata may not transfer perfectly—especially if the migration process focused more on file paths than product attributes. Missing or incorrect alt tags can hurt your SEO and accessibility compliance.

Steps to update and verify alt tags in Magento 2:

+ Check existing alt tags: Go to each product in Catalog > Products and verify the “Alt Text” field in the Images and Videos section.

+ Batch update using CSV import: Export product data via System > Export, edit the image_label column with correct alt text, and re-import.

+ Best practices for writing alt tags

Be descriptive but concise (e.g., “Blue Cotton Summer Dress – Front View”).

Include relevant keywords naturally—avoid keyword stuffing.

Reflect the actual content of the image to improve relevance.

+ Automate alt text generation (optional): Some extensions can auto-generate alt text from product name + attributes, ensuring consistency across the catalog.

Troubleshooting common image migration issues

Even with a smooth migration process, product images can sometimes fail to appear or display incorrectly in Magento 2. The following common issues and their solutions will help you quickly diagnose and fix post-migration image problems.

Images not appearing in the frontend

If product images are missing on the storefront but visible in the Admin panel, it often comes down to file permissions, incorrect media paths, or missing symlinks.

Steps to fix:

+ Check file permissions:

Ensure correct ownership:

bash

chown -R <magento_user>:<magento_group> pub/media

Set proper permissions:

bash

find pub/media -type d -exec chmod 755 {} \;

find pub/media -type f -exec chmod 644 {} \;

+ Verify media path

Images must be located under pub/media/catalog/product in Magento 2.

Check that filenames and paths match database entries in catalog_product_entity_media_gallery and catalog_product_entity_varchar (for labels).

+ Check symlinks: Magento 2 uses symlinks for pub/media in developer mode. If broken, recreate them:

bash

php bin/magento setup:static-content:deploy

php bin/magento cache:flush

Missing thumbnails or swatches

When category thumbnails, product gallery previews, or color swatches don’t load, the cause is often a missing cached image or incorrect role assignment.

Steps to fix:

+ Regenerate image cache: Delete pub/media/catalog/product/cache and let Magento regenerate thumbnails:

bash

rm -rf pub/media/catalog/product/cache

php bin/magento cache:flush

+ Check image roles in product settings

Go to Catalog > Products > Edit product.

Under Images and Videos, ensure images are assigned to the correct roles:

Base Image (main product image)

Small Image (category thumbnails)

Thumbnail (gallery preview)

Swatch Image (for configurable products)

+ Reindex catalog: Run:

bash

php bin/magento indexer:reindex

Broken URLs or 404 errors

Sometimes migrated images exist on the server but fail to load due to incorrect base media URLs or missing rewrite rules.

Steps to fix:

+ Configure Base Media URL in Magento 2 Admin

Go to Stores > Configuration > Web > Base URLs (and Base URLs (Secure)).

Update Base URL for User Media Files to match your domain/CDN path, e.g.,

ruby

https://www.example.com/pub/media/

+ Ensure .htaccess rules are intact

Check that .htaccess in pub/media is present and contains default Magento rewrite rules.

If missing, copy from a fresh Magento 2 installation.

+ Clear and refresh caches

php bin/magento cache:flush

php bin/magento cache:clean

Duplicate images after migration

Duplicate images can appear if the migration process was run multiple times or if Magento is storing the same file under different hash paths.

Steps to fix:

+ Identify duplicates: Use Magento’s media storage report (if available) or run a server-side script to detect identical files:

bash

fdupes -r pub/media/catalog/product

+ Remove duplicates

Delete unnecessary files carefully and reindex afterward.

Make sure database references point to the retained image files.

+ Prevent re-import duplication

If using the Data Migration Tool, ensure --auto or delta migration is configured so it doesn’t re-import unchanged media.

Disable unnecessary sync jobs that might duplicate media during staging or cron runs.

Final thoughts

Migrating product images is more than just moving files—it’s about preserving quality, SEO value, and customer trust. With the right preparation, migration method, and post-migration optimization, you can ensure your Magento 2 store loads fast, looks consistent, and performs at its best. Treat your images as part of your store’s core assets, and they’ll keep working for you long after the upgrade.