Managing product images one by one in Magento 2 can be painfully slow—especially if you’re launching a new collection, updating seasonal items, or migrating from another platform. The good news? Magento 2 offers several ways to import product images in bulk, saving you hours of manual work while keeping your catalog consistent and professional.

In this guide, we’ll walk you through three proven methods for bulk product image import in Magento 2—whether your files are stored on your server, hosted externally, or in cloud storage. You’ll also get a prep checklist, troubleshooting tips, and best practices to ensure your images display perfectly and load fast on your Magento 2 store.

1. Before you start — Preparation checklist

A successful bulk image import in Magento 2 starts long before you click the Import button. If your files are disorganized or your CSV is formatted incorrectly, you’ll end up with broken image links, mismatched products, or import errors. Follow this checklist to avoid headaches and ensure a smooth process.

Organize and name your images properly

The first and most crucial step in a smooth Magento 2 bulk image import is having your images well-organized and consistently named. This ensures Magento can correctly match each file to the right product without manual intervention.

1. Use consistent, descriptive file names

Your file names should describe the product and, where applicable, include attributes like color, angle, or version. Descriptive names make your files easier to manage and help with SEO if they’re later used in public-facing URLs. 

Example naming pattern:

productname-color-angle.jpg

blue-shirt-front.jpg

blue-shirt-back.jpg

blue-shirt-side.jpg

Best practices:

• Keep all lowercase for consistency—some servers are case-sensitive.

• Avoid generic names like image1.jpg or photo.jpg that could lead to overwriting or confusion.

• Avoid spaces and special characters: Magento and many web servers can misinterpret spaces or special characters (&, %, #, ?, @) in file names, causing broken links or failed imports. Replace them with hyphens (-) for word separation or underscores (_) for alternative separation if needed. Example correction:

• ❌ blue shirt (new).jpg

• ✅ blue-shirt-new.jpg

• If each product has multiple images, keep related images grouped when naming. This makes mapping to CSV columns (base_image, small_image, thumbnail_image, additional_images) far easier. Example for SKU SHIRT-BLUE-001:

  • shirt-blue-front.jpg

  • shirt-blue-back.jpg

  • shirt-blue-side.jpg

2. Keep file formats consistent

Maintaining a consistent format across your entire catalog helps minimize compatibility issues during the import process and makes subsequent steps—such as compression, optimization, or conversion to WebP—more efficient and reliable.

In Magento, the supported image formats include JPG, JPEG, and PNG. Among these, JPG/JPEG is often the most suitable choice for standard product images because it offers good compression while maintaining display quality. PNG should be reserved for specific cases that require transparency, such as logos or product images with intricate cutout details. 

3. Store all images in one dedicated folder

Before starting the import, put all images in a single, clearly named folder. 

• If importing from the Magento server, upload them to var/import/images, or a subfolder like var/import/images/product_photos

• If using an external server, store them in one accessible directory with a simple, readable path.

• If using cloud storage (e.g., S3), follow the same single-folder approach inside the configured storage bucket.

Note: If you plan to convert images to WebP later, keeping your naming consistent will make the automated conversion process smoother and avoid filename conflicts.

Take the hassle out of image optimization! Learn how to automate every step—from upload to fast delivery—so your Magento store looks great and loads lightning fast. Start optimizing your images automatically and watch your site performance soar. Check out the complete guide now!

Match image filenames to SKUs

Magento assigns images to products by using the SKU value in your CSV file to match existing product records in the catalog. This means the accuracy of your SKU-to-image mapping is critical for a successful import.

1. An exact match is required

Every SKU in the CSV must match an existing product SKU in Magento exactly, including uppercase and lowercase letters (Magento is case-sensitive). If there’s even a small mismatch—such as an extra space, a missing character, or a case difference—the image will not be assigned.

2. Mapping multiple images to the same product

• For products with multiple images (e.g., front, back, side), the primary image file should be linked in all main image role columns (base_image, small_image, thumbnail_image).

• Additional product images should be listed in the additional_images column, separated by commas and without spaces.

• Magento will automatically associate all listed images with the product that has the matching SKU.

Create the Import CSV File

The CSV file is the “map” Magento uses to connect your product SKUs with the correct image files and assign each image to the right display role. If your CSV is missing key columns or is formatted incorrectly, Magento will fail to link your images—even if the files themselves are uploaded correctly.

1. Required image-related columns

At a minimum, your CSV must contain the following columns for image import:

• sku — The unique product identifier in Magento.

• base_image — The main image shown on the product detail page.

• small_image — The image used in category listings, upsell blocks, and related product sections.

• thumbnail_image — The smaller image used in widgets, the shopping cart, and the mini-cart.

• additional_images — Any extra product images, separated by commas. These could be alternative views, lifestyle shots, or detail close-ups.

Note: Column names can vary slightly depending on your Magento version or import tool, but these are the standard Magento Admin naming conventions.

2. Formatting rules

To ensure Magento processes the CSV correctly:

• Use a leading slash (/) before each filename when importing from the default var/import/images directory. Example: /blue-shirt-front.jpg

• Separate multiple additional images with commas, no spaces. Example: /blue-shirt-back.jpg,/blue-shirt-side.jpg

• Keep case sensitivity in mind — both SKUs and filenames should match exactly as stored on your server.

• If importing from an external server, use the full HTTP or HTTPS URL instead of a filename. Example: https://cdn.example.com/images/blue-shirt-front.jpg

3. Sample CSV snippet

Here’s an example showing a product with one main image and two additional views:

Tip: Start by testing your CSV with 2–3 products to confirm your formatting is correct. Once those imports are without errors, you can confidently run the full bulk import.

Methods to import Magento 2 product images in bulk

Magento 2 supports three primary methods for bulk image import. Each method works best in different scenarios, depending on where your images are stored and how your store is configured. Let’s start with the most common approach—importing from the local server.

Method 1 — Import from local server

This method involves uploading your image files directly to your Magento server, specifically to the var/import/images directory (or a subfolder within it). Magento will then read the image filenames from your CSV and match them to the corresponding product SKUs.

Step-by-step guide: 

1. Upload images to the server

• Use FTP/SFTP (e.g., FileZilla) or your hosting File Manager to upload all image files to var/import/images. You can also create a subfolder like var/import/images/product_photos

• Make sure file permissions are set so Magento can read the images.

2. Prepare the CSV File

• If your images are in the default var/import/images directory, you only need to list the filenames (with a leading slash, e.g., /blue-shirt-front.jpg) in the CSV columns.

• If using a subfolder, include the subfolder name in the Images File Directory during the import process, not in the CSV.

3. Run the import in Magento admin

• Navigate to System → Data Transfer → Import.

• Under Entity Type, select Products.

• In Import Behavior, choose Add/Update.

• Upload your prepared CSV file.

• If your images are in a subfolder, enter the folder path relative to var/import/images in Images File Directory (e.g., product_photos).

• Click Check Data to validate your file. If no errors are found, click Import to start the process.

Pros and cons

Pros:

• Stable and reliable — no dependency on external servers.

• No need for internet-based image fetching, which can slow down imports.

Cons:

• Requires direct server access, which may not be possible for all store owners.

• You must manually upload files to the server before importing.

Method 2 — Import from external server (Remote URLs)

This method allows Magento to pull product images directly from a publicly accessible server using HTTP or HTTPS links. Instead of uploading images to your Magento server, you simply reference their full URLs in the CSV file. This is particularly useful when:

• Your images are already hosted on a CDN or cloud storage (e.g., AWS S3, Google Cloud, Azure).

• You’re migrating from another store and want to avoid downloading/re-uploading images.

Step-by-step guide

1. Ensure images are publicly accessible

• Your image URLs must be reachable without any login or token authentication.

• Test by pasting the URL in a browser — the image should load instantly.

• Example valid link: https://cdn.example.com/products/blue-shirt-front.jpg

2. Prepare the CSV file

• In your CSV’s image-related columns (base_image, small_image, thumbnail_image, additional_images), use the full image URL for each file.

• Example CSV snippet:

3. Run the Import in Magento Admin

• Go to System → Data Transfer → Import.

• Set Entity Type to Products.

• Choose Add/Update in Import Behavior.

• Upload your CSV file.

  • Leave the Images File Directory field empty (because you’re using URLs, not local files).

  • Click Check Data, then Import once validation passes.

Pros and cons

Pros:

• No need to upload files to your Magento server.

• Ideal for pulling images from a CDN or cloud storage.

Cons:

• Requires stable, fast hosting to prevent timeouts during import.

• If image URLs change or hosting goes down, Magento will not be able to fetch the files.

Method 3 — Import from media storage (Already uploaded in Magento)

If your product images are already stored in Magento’s pub/media directory—for example, from a previous import, a staging site, or manual uploads—you can link them to products without re-uploading. Instead of fetching from an external server or uploading to var/import/images, Magento will simply reference the existing files in its media storage.

This method is especially useful for:

• Linking products to images after a catalog migration, where the media folder was copied separately.

• Restoring image associations after a database reset or import that lost image links.

Step-by-step guide

1. Locate your existing images in Magento

• Go to your Magento root folder and navigate to: pub/media/catalog/product

• You’ll see subfolders named according to the first two characters of the image filename. For example: b/l/blue-shirt-front.jpg → subfolders: b/l

• This folder structure is auto-generated by Magento for efficient file storage.

2. Prepare the CSV file

• In your CSV image columns (base_image, small_image, thumbnail_image, additional_images), use the relative path starting from the pub/media/catalog/product directory.

• Example CSV snippet:

3. Run the import in Magento admin

• Go to System → Data Transfer → Import.

• Select Entity Type: Products.

• In Import Behavior, choose Add/Update.

• Upload your CSV file.

• In Images File Directory, enter the path relative to Magento root: pub/media/catalog/product

• Click Check Data, then Import after validation.

Pros and Cons

Pros:

• No need to move or re-upload files—faster imports.

• Ideal when the pub/media folder is already populated.

Cons:

• Requires correct relative paths in the CSV.

• If images are missing in pub/media/catalog/product, the import will fail to link them.

Tip for performance:

If your store already has many JPG or PNG images in pub/media, consider installing a Magento 2 Convert Images to WebP extension. After linking images to products, you can bulk-convert them to WebP for faster load times and better Google PageSpeed scores—without losing quality. 

BSS Commerce – The Trusted Magento 2 Extension Provider

BSS Commerce has built its reputation around three core values: Solution-Oriented, Feature-Rich, and Transparency. With over 10 years of experience and a portfolio of 150+ Magento 2 extensions, we understand store owners’ challenges and deliver practical tools to boost performance, user experience, and sales.

Explore our WebP conversion tool here: https://bsscommerce.com/magento-2-convert-images-to-webp-extension.html 

Reindex and clear cache

After completing your product image import, it’s essential to run Magento’s indexer and cache commands to ensure your store reflects all the changes correctly. Without this step, newly imported images might not appear on the frontend or in the admin panel.

From your Magento root directory, execute these commands:

• php bin/magento indexer:reindex: For reindexing Magento’s data, updating product and catalog information

• php bin/magento cache:flush: For clearing the cache so that the frontend and backend show the latest content.

Additional tips for success

• Avoid spaces in image file names: Spaces can cause import errors or broken image links. Use dashes (-) or underscores (_) instead.

• Use consistent file formats: Stick to JPG or PNG formats to ensure Magento compatibility and smoother processing.

• Split large imports into smaller batches: If importing thousands of images, break your CSV into smaller files to avoid server timeouts or memory issues during import.

Simple steps like avoiding spaces in image file names, using consistent formats, and splitting large import files not only help your bulk image import go smoothly but also contribute to faster loading product pages on your Magento store.

If slow product pages are costing you customers, apply these tips now to optimize your site’s performance and keep shoppers engaged longer: How to fix slow Magento product pages.

Conclusion

Importing product images in bulk is a powerful way to save time and streamline your Magento 2 store management. Whether you choose to upload images directly to your server, use remote URLs, or link images already stored in Magento’s media folder, following the right preparation and import steps ensures a smooth process.

Don’t forget to run the reindexing and clear cache commands after import to make sure your images display correctly. Also, adopting best practices like consistent file naming and splitting large imports will help avoid common pitfalls.

For enhanced site performance, consider converting your imported images to WebP format using trusted extensions like the Magento 2 Convert Images to WebP Extension by BSS Commerce — a reliable provider committed to delivering feature-rich, solution-oriented tools that boost your store’s speed and user experience.

By following this guide, you’ll efficiently manage your product images and provide your customers with a faster, more engaging shopping experience.