WordPress Plugin v2

Overview

Using the Cloudinary WordPress plugin, you can upload and manage your images in Cloudinary directly from your WordPress interface. The plugin also supports automated (single-click) migration of all images from your existing posts to Cloudinary.

Once your WordPress images are stored in Cloudinary, you can take advantage of Cloudinary's transformation, optimization, and responsive image features as well as fast CDN delivery.

Installation

Before you install the Cloudinary plugin, make sure you have a Cloudinary account. Sign up for a free plan, starting with generous usage limits and when your requirements grow, you can easily upgrade to a plan that best fits your needs. More pricing information is available here.

Install or upgrade the plugin from the WordPress Plugins directory. You can open this from the Plugins dashboard by clicking Add New. Search for "Cloudinary" to bring up the Cloudinary Plugin.

Alternatively, you can install the plugin manually:

1. Download the plugin.
2. Click Add New to go to the Plugins Directory.
3. Click Upload Plugin and then Choose file to select the Cloudinary plugin zip file.
4. Click Install Now to begin the installation.
5. Once installed, click Activate Plugin to begin the Cloudinary setup.

Uninstall

To stop using the plugin, you can deactivate and/or uninstall from the Plugins dashboard. When you deactivate the Cloudinary plugin, all assets will be delivered from WordPress storage and any globally defined transformations will no longer be applied. If your storage is configured as Cloudinary only, you’ll need to sync your assets back to WordPress before deactivating the plugin to prevent any issues.

Setup

Once you’ve activated the plugin, a new Cloudinary menu item will be added and you’ll need to connect your Cloudinary account to WordPress.

1. Click Getting started from the Cloudinary menu item and navigate to the Connect tab to open up the connection settings page.

2. Enter your Connection string, then click Connect. You can find your connection string in the Account Details section of the Cloudinary Console Dashboard:
   
   
   

   Caution

   If you’re upgrading from v1.x of the plugin, ensure that you use the same Cloudinary account settings that you used before. If you plan to use a different Cloudinary account, you must change this after completing the initial setup with your existing account and ensuring all your assets are synced.

3. After saving, a new Media Settings item will be available under the Cloudinary menu item. You can use these to configure your Sync settings, how your media is displayed or configure the Cloudinary Product Gallery for use on your site.

Success! Your site is now set up to start using Cloudinary. For new installations, all of your existing media assets will now sync with Cloudinary and be optimized and delivered via CDN. If you've upgraded from v1.x, take a look at how to Sync your media.

See the Media settings section below to adjust the default delivery settings or start adding media with Cloudinary.

Dashboard

The Cloudinary plugin dashboard page displays basic information about your current Cloudinary plan as well as usage and remaining monthly quota information. Here, you will also see your sync status.

Media Settings

Once you're set up correctly, you'll see a new Media Settings menu item under Cloudinary in the WordPress admin panel. This is where you can configure your Cloudinary settings for WordPress.

Sync

The Sync tab allows you to configure and sync your existing media with Cloudinary. By syncing with Cloudinary you can then make use of all the features and functionality for delivering optimized and transformed media.

First, set whether you want to sync your assets automatically, then select where assets uploaded to WordPress are stored within Cloudinary. On initial setup, this will be set to your WordPress installation Domain Name and the folder will be created in Cloudinary. For example, if you installed WordPress on the domain “mywebsite.com”, your assets would be stored in a folder named “mywebsite”. Leave this field blank if you want all of your assets to be uploaded to the root Cloudinary folder; this is not recommended if you're using Cloudinary outside of WordPress.

Auto-Sync

Auto-sync ensures that all of your WordPress assets are automatically synced with Cloudinary when they are added to the WordPress Media Library. Assets must be synced with Cloudinary in order to get all the benefits the Cloudinary plugin offers.

• For new installations, auto-sync is on by default. You can turn this off if you prefer to manage your syncing manually.
• If you're upgrading from v1.x of the plugin, auto-sync is off by default. This will allow you to properly manage the sync process. You can choose to perform a bulk-sync or push individual assets to Cloudinary using the WordPress Media Library.

Bulk-Sync

If a large number of assets exist in your WordPress library before activation of the Cloudinary plugin, you can perform a bulk-sync. Select Sync all media to Cloudinary to begin the bulk-sync.

Sync individual assets

If auto-sync is turned off, you can sync individual assets with Cloudinary using the WordPress Media Library. When hovering over an image in the library, select the Push to Cloudinary option to sync that individual asset.

Storage

The storage setting allows you to select the storage location for your assets. As a minimum, assets must be stored with Cloudinary to be delivered with all the benefits Cloudinary offers.

The three options you can select are:

1. Cloudinary and WordPress - This setting stores all assets in both Cloudinary and WordPress local storage. With this setting, if there are any issues with your Cloudinary account, or you choose to deactivate the Cloudinary plugin, your assets will be delivered directly from WordPress storage with no issues, ensuring a more robust fallback mechanism.
2. Cloudinary and WordPress (low resolution) - This setting stores the original full resolution assets with Cloudinary and a lower resolution compressed version in WordPress, saving space in your local storage. With this setting, if you deactivate the Cloudinary plugin, your assets will be delivered at a much lower resolution directly from WordPress storage. This setting provides a limited fallback mechanism.
3. Cloudinary only - This setting stores all assets in Cloudinary only, any existing assets stored in WordPress will be removed to save space in your local storage. With this setting enabled, you need to manually sync your media back to WordPress before deactivating the plugin. Before setting to Cloudinary only, we recommend creating a full backup of your WordPress site.

The table below demonstrates where an image would be stored for the given options, how it would look and the size of each version:

Storage Setting / Location	Cloudinary	WordPress
Cloudinary and WordPress	117.43 KB	117.43 KB
Cloudinary and WordPress (low resolution)	117.43 KB	54.67 KB
Cloudinary only	117.43 KB

Media Display

Media display is where you can control how your images and videos are delivered on your site.

Image - Global Settings

Here you can specify the global image settings and transformations to be applied to all images (new and existing assets) when they are delivered. These also apply to any featured images.

• Image optimization - Enable image optimization to deliver your images using Cloudinary’s automatic format and quality algorithms for the best tradeoff between visual quality and file size. You can also use Advanced optimization options to manually tune format and quality.
• Image breakpoints - Enable breakpoint generation on upload and set how many breakpoints are created for each image, the byte step and max and min width. This allows you to generate a number of images and serve up an optimal image size depending on the size of the browser or device. These settings use Cloudinary's responsive breakpoint generator to balance the number of image versions generated vs. the file size reduction between each version.
• Custom transformation - Use a custom transformation string to provide a set of transformations to apply globally as a URL transformation string, for example adding watermarks to all images throughout the site. See the image transformation guide for more details.

Alongside the settings, you’ll see a preview of an example image with your transformations applied.

Video - Global Settings

As with the Global Image Settings, this is where you can configure the global settings and transformations for all videos (new and existing assets).

• Video player - Set which video player to use. You can select to use the Cloudinary video player for all videos which gives additional options like autoplay, repeat, and whether to show controls.
• Bitrate - Enable this to limit the bitrate therefore helping to reduce bandwidth and load times.
• Video optimization - Enable video optimization to deliver your videos using Cloudinary’s automatic format and quality algorithms for the best tradeoff between visual quality and file size. You can also use the Advanced optimization options to manually tune format and quality.
• Custom transformation - Use a custom transformation string to provide a set of transformations to apply globally as a URL transformation string. See the video transformation guide for more details.

Gallery settings (Beta)

This is where you can configure the look, feel and behavior of the Cloudinary Gallery block, or for WooCommerce users, you can enable it to replace the default product gallery. You can see a live preview alongside the settings, showing how your gallery will look on your pages and posts.

Media usage

When editing or creating posts or pages, insert your images and videos as normal using the WordPress Media Modal. The Cloudinary plugin adds a new Cloudinary tab to this modal that will display the Cloudinary Media Library, providing a full Digital Asset Management (DAM) solution. From here, you can transform and insert your Cloudinary assets into the WordPress Media Library for usage on your site. All of your assets will be delivered using Cloudinary URLs and include the transformations and optimizations you have defined.

Use the Cloudinary Media Library UI to:

• Upload new images, videos, audio, or other files.
• Insert your images from Cloudinary. The Insert button (shown above) will be displayed when you select assets from the library or when managing individual assets.
• Transform your assets at an individual level before inserting them.
• 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 insert, 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, generate transformations for that asset or insert into WordPress.

For more information on Cloudinary's Digital Asset Management solution, see the Cloudinary DAM documentation.

Cloudinary Gallery (Beta)

The Cloudinary Gallery provides a highly customizable and optimized gallery interface using the Cloudinary Gallery. The gallery is great for product detail pages but can also be used as a way of showcasing images for a variety of other use cases.

To use the gallery, first configure the look and feel using the Gallery settings. When you're happy with the design, add the Cloudinary Gallery block to any page or post and select the media you want to include.

For WooCommerce sites, the gallery can be enabled to replace the default product gallery on all product detail pages.

Asset sync status

The WordPress Media Library includes information about the sync status of your assets with Cloudinary. Switch to list view to see the sync status column; this column contains an icon indicating one of four statuses:

•  Indicates the asset is fully synced with Cloudinary; it exists in both WordPress and Cloudinary and will be delivered using a Cloudinary delivery URL.
•  Indicates the asset syncing with Cloudinary is in progress. You may see this if you change a setting that affects a synced asset, such as the number of breakpoints.
•  Indicates the asset is not synced with Cloudinary. Any un-synced assets can be pushed manually. Hover over the relevant asset and select the Push to Cloudinary option. Alternatively, to sync all assets you can perform a bulk-sync.
•  Indicates there was a problem syncing to Cloudinary. Hovering over the icon will show a message explaining the error. This will most likely be due to a file size limitation or an incompatible file type. Please refer to your package limitation for more information on this.

Transformations

You can apply transformations to all of your media assets to deliver them to your users just the way you want them. For more information on the available transformations take a look at the image or video transformations guides. All transformation strings are set using Cloudinary URL syntax; examples are provided throughout the transformation guides.

You will find the Image Transformation string input field in the global Cloudinary settings as well as when defining different taxonomies. For individual transformations, the Cloudinary Media Library is used to create the transformation and the corresponding transformation string is added to the delivery URL.

Here's how to configure a global transformation that adds a Cloudinary logo overlay using the Custom transformation field:

Transformation hierarchy

Transformation hierarchy is used to ensure the correct transformations are applied to the correct assets in the correct places. You can set transformations at global level, taxonomy level and individual asset level (when inserting from the Cloudinary Media Library), with the option to overwrite or concatenate the transformations to achieve the desired effect.

Global level transformations

Global level transformations apply to all images or video throughout your site. They can be set using the two global settings tabs (one for images and one for videos). Global level transformations can have taxonomy and individual transformations concatenated to the end or they can be overwritten. The best practice for global level transformations is to ensure they don’t edit the content of the media too significantly and therefore would not need to be overwritten. An example would be to add a watermark to all your media assets.

Taxonomy level transformations

Taxonomy level transformations are specific to a defined taxonomy, either a “category” or a “tag”. You can set your transformations when creating or editing the taxonomy. You can then apply the taxonomy to a post or page to see the transformations take effect on the media assets. An example of a taxonomy level transformation would be to apply an overlay or effect relating to that taxonomy e.g. Adding the tag “sale” could overlay a sale banner onto all the media assets in that post or adding a “dog” category could overlay a paw print.

Taxonomy order

When editing your content there will be a setting for “Taxonomy order”. This allows you to configure the order in which the taxonomy level transformations should be applied (if you have multiple). You can also set whether the taxonomy level transformations should overwrite the global transformation.

Individual level transformations

Individual level transformations are performed using the Cloudinary Media Library UI before they are imported into the WordPress Media Library. The transformations are then included in the delivery URL and cannot be overwritten by any other transformation. If you make any subsequent transformations to the same asset at an individual level, they will be imported as new assets to the WordPress Media Library.

If you add a transformed asset to your content, you can specify whether you wish the individual level transformation to overwrite the taxonomy and global level transformations you have defined and therefore only display the individual transformation. To do this, navigate to the asset within the editor and click the asset to display the options in the “block” tab, or select edit (if you’re using the classic editor). You'll see either a radio button or toggle for Overwrite Transformations.

Classic Gutenberg

Examples

The examples below demonstrate how transformations are applied for different combinations of overwrite settings. The result is the Cloudinary URL that is used to deliver the image.

Original image

Example of individual level overwrite

If you overwrite at the individual level only, both the taxonomy and global level transformations are not included in the final delivery URL.

Result

Example of taxonomy level overwrite

If you overwrite at the taxonomy level, you will get both individual and taxonomy level transformations in the final delivery url. The global level transformations will be overwritten.

Result

Example of overwriting at taxonomy and individual level

If you overwrite at both taxonomy and individual level, you will get the same result as just overwriting at individual level, as this will always take precedence.

Result

Example with no overwriting

If you don't overwrite at any level then all transformations will be included in the final delivery URL.

Result

System Report

The system information report is an option that allows you to generate and download a realtime snapshot report about your WordPress site and the Cloudinary plugin. The report can be used to debug any specific issues you're having with your Cloudinary media and will help assist our support team should you need to contact them with any queries.

The report is in JSON format and it includes information about:

• Current WordPress and Cloudinary configuration
• Currently installed plugins
• Any themes that are being used
• Any specifically selected media
• Any specifically selected posts or pages

Once the report is enabled, you'll see a button to download your report. As the report is a realtime snapshot, it will include updated information each time you download it.

Adding media or posts/pages to the report

Adding specific media or posts to your report can help to solve any issues you might be seeing.

Before adding media or posts/pages to your report, ensure that system information reports are enabled. Once enabled, to add items to the report:

1. Navigate to the WordPress Media Library or the Posts/Pages section.
2. Find the media, post or page that you want to add to the report. For media, ensure you're viewing the library in list mode.
3. Hover over the item and select Add to Cloudinary Report.

For Developers

If you're an experienced WordPress developer and are looking to customize and extend the Cloudinary WordPress plugin, you can make use of some additional tools and options to get the best out of your setup.

Setting the connection string as a constant

One way you might want to configure the plugin is to define your Cloudinary connection string as a constant. Setting the constant will prevent any users from editing or updating the associated Cloudinary cloud via the WordPress UI. To set your connection string, add the following line to your wp-config.php file, replacing the key, secret and cloudname with your own values:

define( 'CLOUDINARY_CONNECTION_STRING', 'cloudinary://key:secret@cloudname' );

Actions and filters

The Cloudinary WordPress plugin exposes a number of actions and filters that you can hook into to customize and extend the functionality of the plugin. You can find a full reference of the available options here.

WP-CLI

The WP-CLI can be used to perform a number of tasks on your WordPress site using the command line. The Cloudinary plugin extends this capability by adding two additional CLI commands:

• The analyze command analyzes the current state of your media assets, telling you how many assets you have that are "synced", "unsynced" or "unsupported".

  Copy to clipboard

  wp cloudinary analyze

• The sync command will begin syncing any unsynced assets to Cloudinary. You can use this as an alternative method for syncing your assets in bulk.

  Copy to clipboard

  wp cloudinary sync

 
You may also want to take a look at Cloudinary's five-chapter Guide to Building the Ultimate E-Commerce Website. The guide includes suggestions by e-commerce and technical experts on how to build a versatile marketplace by selecting automated e-commerce and CMS platforms that help you create, modify, and deploy adaptable user experiences.