12.400 SKUs, 31.000 Bilder, ein Wochenende. So sah die Ausgangslage bei einem Möbelhändler aus NRW aus, der im Frühjahr von einem Altsystem auf Adobe Commerce migrierte. Der Produktimport lief in einer Stunde durch. Die Bilder brauchten drei Tage, zwei Support-Tickets und eine Agentur, die am Ende feststellte: Die Bilder lagen im falschen Ordner. Wer Magento 2 Produktbilder per CSV importieren will, scheitert selten am Format — sondern an den stillen Konventionen, die Adobe nirgendwo prominent dokumentiert.
Dabei ist der CSV-Weg auch 2026 die schnellste Methode, tausende Produktbilder in Magento Open Source oder Adobe Commerce zu laden — wenn man die Spielregeln kennt. Dieser Artikel erklärt sie vollständig: die Dateistruktur, die Pflichtenheft-Ordner, die typischen Fehler und die Frage, ab welcher Kataloggröße der CSV-Import zur Sackgasse wird.
Warum landen Bilder im Magento-2-CSV-Import immer im falschen Ordner?
Die wichtigste Zeile der ganzen Geschichte steht nicht in der CSV-Datei, sondern im Dateisystem. Magento 2 erwartet Import-Bilder seit Version 2.3.2 standardmäßig unter pub/media/import. Liegen sie woanders, muss die CSV-Spalte images_file_directory den alternativen Pfad angeben — relativ zum Medienverzeichnis, nicht absolut. Genau hier scheitern nach unserer Erfahrung sieben von zehn ersten Importversuchen.
Der zweite häufige Denkfehler: Die CSV enthält keine URLs und keine Serverpfade, sondern nur Dateinamen — relativ zum Import-Ordner. Steht in der Spalte base_image der Wert /stuhl-eiche-front.jpg, sucht Magento die Datei als pub/media/import/stuhl-eiche-front.jpg. Der führende Slash ist Pflicht, sonst interpretiert Magento den Wert je nach Konfiguration anders. Subfolder funktionieren: /2026/fruehjahr/stuhl-eiche-front.jpg ist erlaubt und bei großen Katalogen sogar ratsam, weil Dateisysteme bei mehr als 10.000 Dateien pro Verzeichnis spürbar träge werden.
pub/media/import liegen, sonst läuft der Import erfolgreich durch und erzeugt Produkte ohne ein einziges Bild.Wer die Dateien hochgeladen hat, sollte die Dateirechte prüfen. Der Webserver-User — bei den meisten deutschen Hoster-Setups www-data oder ein PHP-FPM-User — braucht Leserechte. Ein klassisches Problem bei DACH-Agenturen: Der Bildbestand kommt per rsync vom Fotografen, landet mit Root-Rechten auf dem Server, und der Import meldet kryptische Fehler wie „File not found“, obwohl die Datei sichtbar existiert.
Wie muss die CSV-Datei für den Bildimport aufgebaut sein?
Pro Produkt gibt es zwei Zeilen-Logiken. Die erste Zeile trägt die SKU und die Rollen-Spalten: base_image (das Hauptbild auf der Produktdetailseite), small_image (Listen- und Kategorieansicht) und thumbnail_image (Warenkorb, Mini-Cart). Häufig zeigen alle drei auf dieselbe Datei — Magento rendert die Größen später selbst. Für konfigurierbare Produkte kommt swatch_image dazu, das Farb- oder Materialmuster.
Zusatzbilder landen in additional_images, kommasepariert: /stuhl-seite.jpg,/stuhl-detail.jpg,/stuhl-raum.jpg. Die dazugehörigen Alt-Texte stehen in base_image_label beziehungsweise additional_image_labels. Lassen Sie diese Spalten nicht leer. Google Bildersuche liefert laut Daten mehrerer SEO-Studien bei produktnahen Suchanfragen messbaren Traffic, und Magento übernimmt die Labels eins zu eins als Alt-Attribute. Im DACH-Markt, wo Barrierefreiheit seit dem BFSG ab Juni 2025 auch rechtlich verbindlich ist, sind saubere Alt-Texte ohnehin kein Nice-to-have mehr.
sku, base_image, small_image, thumbnail_image— die erste Zeile pro Produktadditional_imagesplusadditional_image_labels— Galeriebilder, kommasepariertimages_file_directory— nur nötig, wenn Bilder nicht inpub/media/importliegen
Beim Import selbst wählt man im Admin unter System → Import den Entity-Typ „Products“ und das Verhalten. „Add/Update“ ergänzt Bilder, „Replace“ ersetzt den Datensatz komplett — und löscht dabei gnadenlos bestehende Bildzuordnungen, die nicht in der CSV stehen. Für reine Bild-Updates ist „Add/Update“ mit reduzierter Spaltenzahl (sku plus Bildspalten) der sichere Weg. Wer „Delete“ wählt, entfernt Produkte samt Bildern; das gehört nicht in einen Bildimport-Workflow.
Warum schlägt der Magento-2-Bildimport so oft fehl — und wie findet man die Ursache?
Magento meldet Importfehler mit einer Präzision, die man freundlich als ausbaufähig bezeichnen darf. Die drei häufigsten Ursachen in der Praxis:
Groß- und Kleinschreibung. Die CSV sagt Stuhl.JPG, die Datei heißt stuhl.jpg. Unter Windows-Maschinen, auf denen viele Agenturen die CSV vorbereiten, fällt das nicht auf. Auf dem Linux-Produktivserver ist es ein harter Fehler. Wer Fotos aus Studios bekommt, sollte Dateinamen vor dem Upload konsequent normalisieren: Kleinbuchstaben, keine Umlaute, keine Leerzeichen, Bindestriche statt Unterstriche. Deutsche Sonderzeichen in Dateinamen — ein Klassiker bei DACH-Händlern, die ihre Dateien „Küchenstuhl ü.jpg“ nennen — erzeugen je nach Serverkonfiguration Encoding-Fehler, die sich nur im Exception-Log zeigen.
Die Bilder-Prüfung bei der Validierung. Magento 2 bietet vor dem Import den Button „Check Data“. Wer ihn überspringt, importiert auf Verdacht. Die Validierung fängt fehlende Dateien und kaputte Spaltenzuordnungen ab — sie kostet bei 10.000 Zeilen ein paar Minuten und spart Stunden.
Fehlender Cache-Reset nach dem Import. Die Bilder sind korrekt zugeordnet, das Frontend zeigt aber Platzhalter. Grund: Der Katalog-Bildercache unter pub/media/catalog/product/cache hält alte Thumbnails vor. Ein bin/magento catalog:images:resize baut die Größen neu auf, ein anschließender Flush des Page Caches macht die Änderungen sichtbar. Bei Adobe Commerce auf Cloud-Infrastruktur mit Fastly-CDN kommt eine weitere Caching-Ebene dazu — dort muss der Fastly-Purge explizit ausgelöst werden.
Der CSV-Bildimport ist kein technisches Problem, sondern ein Prozessproblem. Die Fehler entstehen zwischen Fotostudio, Agentur und Hoster — nicht im Import-Modul.
Ab wann wird der CSV-Weg zur Sackgasse?
Bis etwa 5.000 SKUs mit überschaubarer Bildmenge ist der native Import völlig ausreichend. Darüber zeigt die Architektur Schwächen, die man kennen sollte, bevor man sie im Produktivbetrieb lernt.
Erstens kopiert Magento jede importierte Datei aus dem Import-Ordner in die Zielstruktur unter pub/media/catalog/product — organisiert nach den ersten beiden Zeichen des Dateinamens. Wer denselben Import zweimal mit leicht veränderten Dateinamen fährt, legt Dubletten an. Bei Katalogen mit 50.000 Bildern wächst der Medienordner so schnell auf das Doppelte, und Backups werden zum Kostenfaktor. Ein periodisches Aufräumen des Import-Ordners ist Pflicht, keine Kür.
Zweitens skaliert der Import-Worker bescheiden. Der native Importer verarbeitet Zeilen sequenziell; für 100.000 Produkte mit je vier Bildern reden wir über Laufzeiten im Stundenbereich und spürbare Last auf der Datenbank. Adobe Commerce bringt mit dem asynchronen Bulk-Import über die REST-API (POST /V1/products mit Media-Endpoints) eine robustere Alternative, die aber Entwicklungsarbeit erfordert.
Drittens das Media-Management insgesamt: Wer Bilder versionieren, automatisch zuschneiden oder kanalübergreifend ausspielen will, stößt an die Grenzen eines Shopsystems. Spätestens hier gehört ein PIM wie Akeneo oder ein DAM vor die Kette — Magento wird Empfänger, nicht Verwalter.
Welche Alternativen zum nativen Import lohnen sich 2026?
Für Agenturen und Händler, die regelmäßig große Bildmengen bewegen, hat sich im Magento-Ökosystem eine klare Werkzeuglandschaft etabliert.
Firebear Improved Import & Export ist der De-facto-Standard unter den Extensions: Der Import akzeptiert Bilder direkt per URL, Google Sheets, Dropbox oder REST-Quelle — der Zwischenschritt über pub/media/import entfällt komplett. Für Lieferanten-Feeds, die Bildlinks statt Dateien liefern, ist das der entscheidende Unterschied. Amasty bietet mit seinem Mass Product Actions-Paket eine Admin-zentrierte Variante für kleinere Teams. Wer vollständig API-getrieben arbeitet, nutzt den Media-Endpoint POST /V1/products/{sku}/media mit Base64-kodierten Bildern — die sauberste Lösung für automatisierte Pipelines, allerdings mit spürbar höherem Entwicklungsaufwand.
Unser Urteil: Der native CSV-Import bleibt das richtige Werkzeug für Migrationen und seltene Großupdates — er ist kostenlos, dokumentiert und auf jeder Magento-Instanz verfügbar. Wer wöchentlich Bilder nachlädt oder Feeds aus mehreren Quellen konsolidiert, sollte die Extension-Investition nicht scheuen; die Lizenzkosten amortisieren sich bei den üblichen DACH-Agenturstundensätzen nach zwei ersparten Import-Wochenenden.
Die eigentliche Frage für 2026 ist ohnehin eine andere: Wie lange bleibt der manuelle Bildimport überhaupt ein Thema? Adobe drückt Commerce zunehmend Richtung SaaS-naher Services, KI-gestützte Asset-Pipelines erzeugen Alt-Texte und Zuschnitte automatisch, und PIM-Systeme übernehmen die Bildlogistik komplett. Wer heute noch jede Kollektion per FTP und CSV einspielt, sollte den Prozess nicht optimieren, sondern abschaffen — bevor der Wettbewerb es tut.