The media manager is the central module for managing images, videos and other media in Shopware. The module includes a convenient uploader, that allows for a simple upload process utilizing drag&drop.

The module

The module contains four sections. At the top you'll find the actionbar offering the following actions:

  • Search for an album (1): Searches for an album.
  • Add file (2): Opens the file manager to pick and choose files to upload.
  • Replace marked file(s) (3): Replaces the marked file(s).
  • Delete marked file(s) (4): Deletes the marked file(s).
  • Display as table (5): Switches the grid view to a table view. By default this is set to grid view. Selecting "table view" from the menu changes the data display and also the button's caption.
  • Search for media (6): Searches for media files.

On the left side of the window (7) you'll find a list of all your albums and subalbums. You can create and delete your own albums here, except for the main albums which are not deletable. In the middle section (8) all media found in the active folder/album is displayed. Above that there is the drag&drop-area. If your browser supports drag&drop you can upload files by dragging them onto the d&d-zone. If the file format supports thumbnails, you will see a small preview-thumbnail of your files. In the more information (9)-section you can find additional information regarding your selected files, for example: Download link, name, upload date, type, resolution and the file's URL. Try to avoid static links towards your media. Linking statically is not recommended, instead you should link the file dynamically by using the Shopware MediaService.

Adding/deleting media in an album

You can add media to your album in two different ways. The easiest way is to select the album you want to upload the media to and click Add file to upload your files. The files will be assigned directly to the selected album and if possible even thumbnails will be created.

Alternatively you can move already uploaded files to other albums. Simply drag&drop the media onto your desired album. When you upload new files, the media manager will try and generate preview-thumbnails. Please note that thumbnails can only be created for image-files, other file types won't get thumbnails. You can edit the thumbnail specifications in the album settings by right clicking on the respective album and selecting "settings".

Please note that individually created thumbnail sizes in the main album are not automatically transferred to the subalbums. In case you have set new size values, you will have to create them in every single subalbum in order to keep a consistent look. Only when creating new subalbums those will inherit the thumbnail settings from the main album.

You can always delete files via the media manager by marking these files (tick the checkbox on the left of each row) and click on delete marked files. The files and their thumbnails will be deleted from the server, but note that the assignment to the deleted file or other static links will NOT be deleted, you have to delete these assignments manually!

Replace media

As of Shopware 5.3 it is possible to replace existing media files directly via the media manager. You can even swap out different file formats and types. E.g. you can replace .jpg with .png-files. In this case only the filename extension is changed, the image name will remain the same.

To replace an existing image, select the image(s) and click on the Replace media button. In the following window, you can choose a new image to replace the old one. This way, it is also possible to replace multiple images at the same time.

Browsercaching may cause old images to still appear to be there after replacing them. These cached files can not be accessed or replaced by Shopware. It may thus be necessary to empty the browser's cache via the settings tab.

Creating a new album

You can simply create a new album by clicking the right mouse button in a free area of you album overview and choosing create new album. If you have already selected an album the new one will be created as a subalbum to the latter one (1).

Alternatively you also can click Add album (2) on the left side of the footer to create a new album. According to which album was chosen before, a new main album or a subalbum will be created. Subalbums also inherit the thumbnail settings. Main albums will come without any thumbail settings and will have to be configured manually.

Deleting an album

To delete an album, right click on the particular album and select delete album (1). Alternatively you can delete your album by selecting it and clicking delete album (2) on the left of the footer.

Media located in a deleted album will NOT be deleted alongside the album, as you might expect! If you delete an album, the contained media will be moved to the folder "Unsortiert".

Album settings

To get into the settings, just rightclick the desired album and click Album settings (1)' or simply press the gear (2)-icon to open the following window:

  • Album name (1): Here you can change the name of the album.
  • Thumbnails (2): This decides whether thumbnails are generated in this album or not.
  • Album icon (3): Here you can choose between a set of icons for your album to find and access frequently used albums even faster.
  • Thumbnail size (4):' Here you can set new thumbnail sizes. The default format is "200x200px". After setting a new size, click create thumbnail to generate a thumbnail of this size. By clicking generate thumbnails you can generate all thumbnails for this album (again).
  • Thumbnail quality (5): Set the desired thumbnail quality > Possible values are between 1 and 100, the bigger the value, the better the quality, but the file size will increase accordingly.
  • High resolution thumbnails - From Shopware 5 (6): Generates thumbnails with higher resolutions. This option is meant for devices with relatively high pixel density.
  • High resolution thumbnail quality - From Shopware 5 (7): Set the desired high resolution thumbnail quality > Value between 1 and 100, the bigger the value, the better the quality, but at the same time file size will increase.
  • current active thumbnail sizes (8): Here you see the current thumbnail size for your album.

If you made changes to your thumbnail settings, e.g. created new sizes, this has no effect on already uploaded files in the album. If you made any changes, you will have to generate the albums' thumbnails once more. With respect to the quantity, quality and resolution of your media, that process may take some time!

Thumbnail sizes

Default thumbnail sizes for the items are:

  • 0 = 200x200
  • 1 = 600x600
  • 2 = 1280x1280

Tips & Tricks

Thumbnail sizes of Shopware 5

The Responsive theme needs new thumbnail sizes which are the following:

AlbumThumbnail size
Shopping worlds800x800 1280x1280 1920x1920
Banner800x800 1280x1280 1920x1920
Item200x200 600x600 1280x1280
Blog200x200 600x600 1280x1280

High resolution thumbnails

A conventional office display has a pixel density of around 72 ppi (pixel per inch). Some mobile devices have a pixel density of 500 ppi and more. This may cause images to appear relatively small, because of the relatively high resolution on a relatively small screen. To solve this problem, Shopware generates high resolution thumbnails with a double resolution method. With these thumbnails all images can be displayed correctly on high ppi devices without becoming blurry. Please note that Shopware never upscales images, so take care of uploading images with a resolution of at least the biggest high resolution thumbnail in the shop. If you upload an image the size of e.g. 500x500px it won't ever get bigger than 500x500px.

In the image above the high resolution thumbnails will be generated with max. 400x400px, 1200x1200px and 2560x2560px thereby considering and keeping the image ratio. Shopware always uses the longest side of a picture and scales it to the desired size.

Folder structure

Files will not be stored in only one folder anymore. A hash derived from the respective filename will be used to generate a folder name, in which the file then will be saved. For example /media/image/1d/4a/8c/myImage.jpg. After updating, Shopware automatically migrates the files into the new structure by opening the images in the frontend. Alternatively you also can migrate the files via a shell command. The particular command and code can be found in the "shell tools" area below.

Recycle bin

The media manager is equipped with a recycle bin, which automatically collects unused images from the "item"-album. To use this feature, activate the "Media Garbage Collector"-Cronjob, that collects all unused images and discards them by moving them to the recycle bin. You can clear the recycle bin manually in the media manager by rightclicking the recycle bin and select empty recycle bin or simply click the red clear icon.

3D Model Support

As of Shopware 5.2.4 the Media Manager supports the following 3D Models:

  • .dae
  • .obj
  • .fbx
  • .spx
  • .3ds
  • .3mf
  • .blend
  • .awd
  • .ply
  • .pcd
  • .stl
  • .skp

Please note that this is not yet final. You can upload models and manage files in the Media Manager now. But there is no way of displaying those models in the frontend yet.

Shell tools

The following section describes shell commands which are working on the server's shell. Every action you set off will be processed without hesitation and any check back. Commands will be execute by hitting ENTER. You should only use these tools, if you are confident with what you are doing and always remember to keep your backups up to date!

Many actions performed in the media manager can also be executed in the shell. We assume, that you have a shell connection and you're located in the Shopware root folder. There you can use the following shell commands:

  • php bin/console sw:media:migrate - migrates media from the old (pre 5.1) into the new (from 5.1) structure.
  • php bin/console sw:media:cleanup - moves unused media into the recycle bin (from 5.1)
  • php bin/console sw:media:cleanup --delete - moves unused media into the recycle bin and empties it. (from 5.1)
  • php bin/console sw:thumbnail:cleanup - deletes unused thumbnails from all albums
  • php bin/console sw:thumbnail:generate - generates all thumbnails. If executed via shell, this action works much faster than the same action executed in the backend. Either way the process may take some time depending on the quantity, quality and general settings of your media.
  • php bin/console sw:media:cleanup - Searches the installation directory directly on the file basis for images, then creates an index of all originals and thumbnails and deletes orphaned thumbnails (Since Shopware 5.3.0).

You can also execute options with most commands. Use " -h" to open the help-file. Here you can find a list of available commands and options.

Defining permitted file types in the Media Manager

The config.php allows you to define which file types can be uploaded via the Media Manager.

Please note that some basic media files can generally be uploaded, e.g. jpg, png and pdf.
In addition, for security reasons, uploading executable files such as php, com and exe is generally prohibited, even if the file extensions are entered in the whitelist.

In the following example code for the config.php you can upload docx and xlsx files:

 'media' => [
        'whitelist' => [

The file extensions are not case-sensitive.

Shopware Media Optimizer

Using this tool you can optimize your media directly in Shopware to save disk size and traffic to optimize the load of your page, which also optimizes your google pagespeed rank.

Keep in mind:The optimisation of your media files is made lossless, your files will not be compressed. The optimisation only strips meta data and for displaying unnecessary data to shrink the filesize! To compress the files, you should still use the shopware internal compression.
Apparent from our tests, another compression by these tools won't shrink your files again, so it's enough to compress them by using the Shopware settings and just let the tools optimize the files lossless.

Uploading new images

While uploading new files using the media manager, the optimizer automatically generates optimized thumbnails of your media. The original will remain unaffected.

This way we make sure, that you are able to generate new thumbnails from your media using the real original.

Update of existing media files without ssh

When you've e.g. updated Shopware and you already have your system running, you can regenerate all your thumbnails. At regenerating all thumbnails, those files will also processed by the optimizer, the original will remain unaffected here as well!

Manually optimization via Shell

To optimize your media manually, you need to open an ssh session, navigate in the Shopware root directory and execute the following command to start optimizing:

bin/console sw:media:optimize [parameter] [path]

Shopware now scans your file system for media and optimize them.

Keep in mind: This command will check the whole Shopware installation for media files and optimizes them by default. If you have other non-Shopware media files, this command will optimize them too! So if you want to optimize only your Shopware media files, make sure to add the path to your command to optimize just the files in this desired directory.

Here we have a few examples:

// Help
bin/console sw:media:optimize -h
// Info about the optimization tools
bin/console sw:media:optimize -i
// Optimize media files just in this folder
bin/console sw:media:optimize /var/www/media
// Limit the files to gather by date/time
bin/console sw:media:optimize -m
// Verbose
bin/console sw:media:optimize -v

The different optimizers

Shopware can use the following tools by default:

ProgrammSupported MIME-Types
jpegoptimimage/jpeg, image/jpg
jpegtranimage/jpeg, image/jpg

If at least one of these tools is installed, the supported MIME-types will be optimized over this tool. If more tools are installed, an internal logic will ensure, that only the better tools is used for optimizing your media files. If no tool is installed, the process will finish without any optimization.

Please ask your hoster about these tools and let him install at least one per used MIME-type, we suggest jpegtran & optipng.

Extend the optimizer

The media optimizer can be extended using plugins to include more tools or setup the existing tools more individual. If you need such an extension, please take a look at our developer documentation for the media optimizer.

Was this article helpful?