Media import

Products and categories can reference images in a media (or category image) column — URLs or paths, list-delimited. Media import is usually the slowest part of a catalogue import, so Fujin Shuttle offers three strategies with different speed/safety trade-offs, plus a separate choice for thumbnails.

All three strategies share a concurrent, non-blocking download front-end (amphp/http-client, 32 downloads in flight) and a single batched dedup lookup, so they hide latency well against remote image hosts. Existing media names dedupe and skip the download.

Turn it off entirely

Set mediaDownload = off (or simply omit the media column) to skip media. With media off, the products insert path runs at full speed (~5,300 rows/s in the benchmarks).

Strategies

Choose with the mediaImportMode config or the --media-mode CLI flag.

filesaver — safe (default)

Runs each file through Shopware's own FileSaver pipeline. Full metadata, media type, translations, thumbnail-capable — the most correct option. The per-file blocking persist (~5 ms) is the floor, so it's the slowest (~133–150 rows/s with media in the benchmarks).

Pick this when correctness matters more than speed, or when you rely on Shopware media events.

raw — fastest

Bypasses FileSaver: downloads concurrently, computes metadata with getimagesizefromstring, places the file via Shopware's media path strategy and public filesystem, and raw bulk-INSERTs the media + media_translation rows through the async pool (in batches, to cap RAM). Media is verified served and DAL-compatible. No thumbnails by default — pair it with a thumbnail mode below.

Fastest by a wide margin (~670–1,175 rows/s with media). Pick this for large cold loads where you'll generate thumbnails separately.

worker — safe + parallel

Shards the fresh sources across mediaWorkers subprocesses (the internal fujin:shuttle:media-worker command), each running the filesaver pipeline. Reuses Shopware's pipeline for full correctness while parallelising; scales with mediaWorkers up toward the core count (~414–573 rows/s).

Pick this when you want filesaver correctness but more throughput.

Mode	Speed (with media)	Correctness	Thumbnails
filesaver	~133–150 rows/s	full Shopware pipeline	yes
raw	~670–1,175 rows/s	DAL-compatible, no events	none (generate separately)
worker	~414–573 rows/s (× workers)	full Shopware pipeline	yes

Thumbnails

Choose with mediaThumbnails:

Mode	Behaviour
queued (default)	Dispatch thumbnail jobs to the message queue — fast import, thumbnails generated in the background by the messenger worker (run more workers for more throughput).
sync	Generate thumbnails inline during the import — the import finishes only once thumbnails are done; no worker needed.
none	Skip thumbnails — run bin/console media:generate-thumbnails afterwards.

sync / none require raw

sync and none are only valid with the raw media strategy and are disabled for filesaver / worker, which always queue thumbnails via Shopware's pipeline.

Tuning knobs

Where	Knob	Default	Note
admin / CLI	mediaImportMode / --media-mode	filesaver	raw fastest, worker safe + parallel
admin / CLI	mediaWorkers / --media-workers	8	raise toward core count for worker
admin / CLI	concurrency / --concurrency	8	batches in flight (matters on remote DB)
admin	mediaThumbnails	queued	sync/none need raw
code	MediaImport::DOWNLOAD_CONCURRENCY	32	raise for high-latency remote image hosts
code	MediaImport::RAW_BATCH	2000	raw-mode download+insert batch (caps RAM)

For the full benchmark breakdown and how the media path was optimised, see Performance & tuning.