Image Handling

Product images are complex. This page covers every image setting and how to use it.

How Images Work in the Plugin

When your CSV has an Images column with URLs, the plugin:

1. Downloads each image to your Media Library
2. Adds it as an attachment post
3. Links it to the product (first image = featured, rest = gallery)
4. Caches — the same URL downloads only once even if used by many products

Three Image Modes

Settings → Image & Media — pick one:

Mode 1 — Download Images (Default)

Download Images: Yes

The plugin downloads every image URL during import.

Pros:

• Images live in your Media Library (no external dependencies)
• Works offline once downloaded
• Can be resized or watermarked

Cons:

• Slower imports (each image takes 200ms-2s)
• Uses disk space
• Can hit hosting disk quotas

Best for: Small to medium stores with good hosting.

Mode 2 — Use External URLs

Use External URLs: Yes
Download Images: No

The plugin stores the URL directly without downloading.

Pros:

• Fast imports (no download)
• No disk space used
• Images stay hosted on the source CDN

Cons:

• If source server goes down, your images break
• Cannot resize or watermark
• Some themes do not support external URLs

Best for: Very large stores, dropshipping, CDN-hosted catalogs.

Mode 3 — Deferred Image Import (Best of Both)

Download Images: Yes
Deferred Image Import: Yes

Import finishes fast. Images download in the background via a queue.

Pros:

• Import finishes in seconds (images come later)
• Images end up in Media Library like Mode 1
• Good for large imports

Cons:

• Products show broken image for a few minutes after import
• Requires WordPress cron to run

Best for: Stores importing 10,000+ products with images.

Image Column Format

In your CSV, the Images column supports:

Single Image

Images
https://example.com/product1.jpg

Multiple Images (Gallery)

Images
"https://example.com/p1.jpg, https://example.com/p2.jpg, https://example.com/p3.jpg"

First URL = featured image. Rest go in product gallery.

Pipe-Separated (If URLs Contain Commas)

Images
"https://example.com/p1.jpg|https://example.com/p2.jpg"

Set the separator in wizard Step 2 → Separators → Multiple value separator.

Image Sources

The plugin downloads from any:

• HTTP / HTTPS URL
• FTP URL (ftp://user:pass@host/path/image.jpg)
• Local server path (/wp-content/uploads/imports/image.jpg)

Image Resizing

Save disk space by resizing images after download.

Settings

Resize Images: Yes
Max Image Width: 1200
Max Image Height: 1200

After download, the plugin checks each image:

• If width > 1200 or height > 1200, it resizes
• Maintains aspect ratio
• Saves the resized version to Media Library

Recommended Sizes

Smaller = faster load times, less disk space.

Image Watermarking

Add a watermark to every imported image.

Settings

Apply Watermark: Yes
Watermark Type: Text  (or Image)

Text Watermark

Watermark Type: Text
Watermark Text: © Your Store 2026

The plugin overlays the text on each image.

Image Watermark (Logo)

Watermark Type: Image
Watermark Image URL: https://your-site.com/logo-watermark.png

The plugin overlays your logo on each image.

Position

Pick where the watermark appears:

• top-left
• top-right
• bottom-left
• bottom-right
• center

Opacity

0 = invisible, 100 = fully solid.

Typical: 40-60 for subtle watermarks.

Preview

There is no live preview in the plugin (yet). Test with a small import first.

Featured Image vs Gallery

By default:

• First image in the list → featured image (main product photo)
• Rest → product gallery (thumbnails below main photo)

Change the Featured Image

Use a separate column:

SKU,Featured Image,Gallery Images
WK-001,https://example.com/main.jpg,"https://example.com/g1.jpg, https://example.com/g2.jpg"

Map in Step 2.

Preventing Duplicate Images

The plugin caches downloaded images. If 10 products share the same image URL, it downloads once.

How Caching Works

• URL is hashed (SHA-256)
• Hash checked in Media Library
• If exists, reuse
• If not, download and store

This applies per-run. Future runs check again.

Image Watermark Engine

The plugin uses GD or Imagick (whichever is available) for watermarking.

Requirements

• PHP gd extension (usually installed by default)
• OR PHP imagick extension (better quality)

Check via phpinfo() or ask your host.

Fixing Broken Images

Problem 1 — 404 Errors

Some URLs return 404. Check the log:

grep "404" /wp-content/uploads/wkaie-logs/run-123.log

Fix the URLs in your CSV.

Problem 2 — Timeout Errors

Large images time out. Options:

• Increase max_execution_time
• Use Deferred Image Import
• Host images closer to your server

Problem 3 — Wrong Image on Product

Usually a mapping issue. Check Step 2 column mapping.

Problem 4 — Images Not Showing on Frontend

• Media Library should show them
• Clear browser cache
• Check theme supports featured images
• Run Health Check

Problem 5 — Out of Memory

PHP Fatal error: Allowed memory size exhausted

Fix:

• Increase WP_MEMORY_LIMIT to 512M or 1G
• Resize images smaller during import
• Use Deferred mode

Removing Source Files After Import

For FTP/SFTP image sources, you can delete the source file after successful import.

Delete Source on Import: Yes

Saves space on the source server.

Alt Text and SEO

WooCommerce stores image alt text. Plugin supports:

SKU,Images,Image Alt
WK-001,https://example.com/shirt.jpg,Red Cotton T-Shirt Product Photo

For multiple images with different alt text:

SKU,Images,Image Alt
WK-001,"url1.jpg, url2.jpg, url3.jpg","Front view, Side view, Back view"

Image Dimensions for WooCommerce

Recommended by WooCommerce:

WooCommerce auto-generates these from uploaded originals. Your originals should be at least 600×600, ideally 1200×1200+.

Troubleshooting

Performance Tips

• Resize to 1200×1200 or smaller
• Use WebP format if possible (50% smaller than JPG)
• Use a CDN (Cloudflare, etc.) in front of Media Library
• Enable Deferred Image Import for large catalogs
• Clean up unused images periodically

Related Pages

• Products Import — Image columns
• Settings → Image & Media
• Troubleshooting → Images