Magento Extension

The Cloudinary extension is available for both Magento 1 and Magento 2. The Magento 2 extension includes support for video as well as other minor differences. Much of the information in this guide is relevant for both versions. Where functionality differs, Magento 2 behavior is described first, and the differences in Magento 1 are highlighted.


The Cloudinary Magento extension links your Magento website to your Cloudinary account, allowing your teams to manage and automatically serve all your product, category, and content management system (CMS) images directly from Cloudinary. You can apply transformations to change the visual appearance or resize to support multiple devices, and deliver your assets in the optimal format and quality via the most advanced Content Delivery Networks (CDNs).

Get started

Before you install the extension, make sure you have a Cloudinary account. You can start by signing up for a free plan. When your requirements grow, you can upgrade to a plan that best fits your needs.

Once you have your Cloudinary account, download and install the extension from the Magento Marketplace. (For Magento 1, you can find the extension here).


After you download and install the extension, follow these steps to configure the extension for the first time and connect it to your Cloudinary account:

  1. In the Magento Admin Panel, select Stores > Configuration.
    If you're using Magento 1, skip to step 2 and open Configuration from the Cloudinary top-menu item.
  2. On the Configuration page, open the Cloudinary section in the left-hand sidebar and select Settings.
  3. In the Cloudinary Setup section of this page:
    • Set your Cloudinary Account Credentials (copy the text in the Environment variable as found in the dashboard of the Cloudinary Management Console). The format should be cloudinary://{API_Key}:{API_Secret}@{Cloud_Name}, this is the text after "CLOUDINARY_URL=".

      Account details example
    • Set Enable Cloudinary to Yes.
    • Further options can be specified in the Cloudinary Configuration and Default Image Transformations.
    • Click Save Config at the top of the page.
  4. Go to System > Cache Management and refresh your Configuration and Page caches.

From this point onwards, any new media assets you upload can be delivered via Cloudinary.

Migrate media to Cloudinary

You can migrate your existing media assets to Cloudinary in two different ways:

  • Enable Auto Upload Mapping to automatically upload existing media assets to Cloudinary when they are first requested by a user. This option can be set in the Cloudinary Configuration section of the Cloudinary settings.


  • Migrate your media in bulk.
    • For Magento 2, use the Magento command line tool:
      1. From the command line, run the cloudinary:upload:all command. If you are currently located within Magento's parent directory, the correct command is:
        bin/magento cloudinary:upload:all.
      2. You can follow the progress of the migration from the command line. Keep your terminal window open while the uploads are in progress.
      3. When all media assets have been uploaded, return to System > Cache Management in the Magento Admin Panel and refresh all caches.
    • For Magento 1:
      1. Make sure you have cron jobs defined on your Magento server.
      2. In the Magento Admin Panel, select Cloudinary > Manual Migration.
      3. Click Start Migration. The migration takes place in the background via cron, so you can close the Manual Migration page or keep it open to track its progress. Any errors that prevent migration will be shown on the Manual Migration page. If this happens, click Stop Migration , resolve the problem, and then start the migration again.
      4. When the migration is complete, select System > Cache Management. Select all required cache types. Then select Refresh from the Actions drop-down above the options grid and click Submit.

The initial migration process may take a while, especially if you have many media assets.


With Cloudinary, you can add and deliver both images and videos. The Cloudinary configuration page has multiple options to change the behavior of the Cloudinary extension when delivering images and video. These are:

  • Media Delivery Domain Sharding - Enable multiple subdomains for Cloudinary delivery URLs in order to increase page loading speed. This is enabled by default.
  • Auto Upload Mapping - Automatically upload media assets from your site to Cloudinary (if they don’t already exist in your account). Use this to lazily migrate your assets, as the upload will occur only when the asset is first requested by a user. See Auto-Upload for more information on how this works in Cloudinary.
  • Automatic Image Format Optimization - Automatically deliver images converted to modern image formats based on viewing device and browser. For example, deliver WebP on Chrome and JPEG-XR on Internet Explorer for better performance and user experience. This is enabled by default. See how to optimize image format for more information.
  • Image Quality - Adjust the quality of generated images to balance between visual quality and file size minimization. The quality setting defaults to use Cloudinary’s automatic quality algorithm. This is particularly relevant for JPEG and WebP compression levels. See how to optimize image quality for more information.
  • Image Cropping Gravity - Define the part of the image to focus on when cropping images in order to better match your graphic design. This setting will have no effect if ‘Magento’s Default’ is selected. See documentation on gravity for possible values and how they work.
  • Image Device Pixel Ratio (DPR) - Use a DPR value higher than 1.0 to generate and deliver hi-res images for better visual results on HiDPI devices, such as Retina Display devices. This is set to 1.0 by default, but can be increased to 2.0.
  • Global custom transformations - Apply additional transformations to every image and video you deliver. For example, you could add a semi-transparent company logo watermark to every asset. Specify the transformation parameters in the URL format as described in Cloudinary's image transformation guide. For a list of all available transformation parameters, see image transformation reference.
  • Product Gallery - Enable Cloudinary’s interactive media gallery interface to deliver your optimized product images and videos. See the Product Gallery guide for more information.
    • Select the color scheme for the gallery to match your brand.
    • Configure the navigation, zoom type and position, and the behavior of the transitions between images.
    • Configure all aspects of the carousel, including whether to use thumbnails or indicators as well as the thumbnail size and presentation.
    • Extend the functionality by configuring custom parameters. See product gallery reference.
  • Lazy Loading - Only load your images when scrolled into view.
    • Configure whether to apply to your CMS blocks, and optionally, which blocks to exclude from lazy loading.
    • Set the threshold for how many pixels from the top of the page before lazy loading is applied to your images.
    • Choose an effect for how the images are loaded.
    • Choose a placeholder type such as blur or pixelate.

Managing media

You can manage your media assets for your Magento site using the Cloudinary Media Library. Enjoy a full Digital Asset Management (DAM) solution directly through Magento.

Media Library UI

Use the Cloudinary Media Library UI to:

  • Upload new images, videos, audio, or other files.
  • Create and navigate through folders or share folders with user groups.
  • Create and browse collections or share collections with user groups or external parties.
  • Perform advanced searches.
  • Select multiple assets to perform bulk operations including delete, add/edit tags, move, download, or review moderated assets.
  • Select a single asset to view or update basic asset details, view or activate advanced asset analysis operations, or to generate transformations for that asset.

Be careful when deleting or renaming an asset using the Cloudinary Media Library. The plugin will sync this change to Magento and can therefore result in broken image and video URLs.

To insert media from Cloudinary, open the Cloudinary Media Library by clicking Add from Cloudinary. You can find it in the following places:

  • Managing your catalog - Add category and product images to your catalog directly from the Cloudinary Media Library.
  • Managing your site content - Add media from Cloudinary to all pages on your Magento site using the Media Library.


The Cloudinary Media Library allows you to perform transformations on individual assets before inserting them to your Magento site. Have a look at the image transformations guide for more information on the available transformations.

If you have global transformations defined, these will be combined with the transformations you perform at an individual level.

✔️ Feedback sent!