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 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.

Setup

Once you’ve activated the plugin, you’ll need to connect your Cloudinary account to WordPress.

1. Click Connect from the Cloudinary menu item to open up the connection settings page.

2. Enter your “Cloudinary environment variable”, then click save. You can find your environment variable in the "Account Details" section of the Cloudinary Console Dashboard:
   
   
   

   Caution

   
   
   

   • If you’re upgrading from version 1 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, additional settings tabs will be available, use these to configure your Global Transformations or Sync Media.

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 version 1, take a look at how to Sync your media.

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

Dashboard

The Cloudinary plugin dashboard page displays basic information about the Cloudinary plugin. If your account is connected correctly, you'll see your Cloudinary usage and remaining monthly quota, as well as the option to upgrade your plan or view the main Cloudinary Dashboard.

Configuration

Once you're set up correctly, you'll see a new Cloudinary menu item in the WordPress admin panel. This is where you can configure your Cloudinary settings for WordPress. Select Global transformations to configure your Global Image and Global Video settings:

Global Image Settings

Here you can specify the global image settings and transformations to be applied to all images (new and existing assets) on the front end. These also apply to any featured images.

Responsive Image Settings

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.

Delivery Settings

Configure global delivery settings to control how all of your images look when delivered. You can set:

• Image format and quality, which allows you to optimize your images for the best trade-off between file size and image quality. Both format and quality will default to “Auto”, which will apply an algorithm to automatically determine the optimum value.
• Image transformation string, which allows you 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.

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

Global Video 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). You can set:

• Whether to use the Cloudinary video player for all videos, and additional options like autoplay, repeat, and whether to show controls.
• The Bitrate limit which is used to limit the bitrate and therefore helps to reduce bandwidth and load times.
• Video Transformation string which allows you to provide a set of transformations to apply globally as a URL transformation string. See the video transformation guide for more details.

Cloudinary will automatically select the video codec for the video to normalize and optimize it for web. See the video transformation guide for more details on transforming your videos.

Sync Media

The Sync Media 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 version 1 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.

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

Bulk-Sync

If you have a large number of assets in WordPress already, you can perform a bulk-sync. Select Sync all media to Cloudinary to begin the bulk-sync. You can also lazily migrate your existing media. If Auto-Sync is enabled, any asset that already exists in the WordPress Media Library will be added to Cloudinary on-demand when the image is viewed by a user.

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.

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.

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 Image Transformation string 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