If you are using Cloudinary for media asset delivery and storage, you can easily migrate to ImageKit without changing existing URLs. ImageKit provides tools and features that make the migration process seamless and easy. These capabilities have helped companies migrate in days instead of months with zero downtime.

Based on our experience of having done this migration for several customers, the following steps will help you migrate successfully to ImageKit with minimal effort and no downtime.

Basic steps for migration

Connect your current or backup media storage to ImageKit. This could be your Cloudinary backup bucket or any other cloud storage where your assets are stored
Set up ImageKit for media delivery with the use of ImageKit URL Endpoints, Cloudinary URL rewriter, custom domain names, and other features
Test and make the switch to ImageKit for media delivery.
Switch new asset uploads to ImageKit's Media Library, if needed, using ImageKit's upload APIs.
Move old assets to ImageKit, using one of the few migration methods available

If your setup or requirement is more complex, you can always contact our team at support@imagekit.io for assistance.

Connect your storage to ImageKit

There are three ways in which this can be done

Using Cloudinary Backup Bucket

If you store assets in Cloudinary's Media Library, you can refer to their documentation and enable backup to your own AWS S3 bucket. Once this is turned on, all newly uploaded assets will automatically get added to this backup bucket. You will have to perform a one-time backup for your older assets to this bucket.

Once the backup is created, you can connect it using the Cloudinary Backup Bucket integration in ImageKit.

Using a cloud storage

Suppose you upload assets to an object storage like AWS S3 and use that with Cloudinary or have moved your assets to a cloud storage. In that case, you can connect it like a standard cloud storage bucket to ImageKit using one of the integrations available here.

Using a Web Server

You can also add https://res.cloudinary.com/<your_cloudinary_id> as a Web Server type of external storage in ImageKit. When a request comes to ImageKit, we will get the assets from Cloudinary and perform optimizations and transformations on it. However, we do not recommend using this for the long run. If you use this, then you should definitely migrate new asset uploads and old asset uploads to ImageKit.

Cloudinary URLs have /image/upload, /video/upload etc. in their URLs. You may or may not want them in your final URLs with ImageKit, or your connected external storage may not have files on these paths. To handle this, you can change the Cloudinary backup bucket configuration or modify the "Asset and Delivery Type" setting of the Cloudinary URL Rewriter, as explained later.

Set up ImageKit for Media Delivery

By the end of this section, we will have working URLs in ImageKit that can access the images on the same or similar paths to those in Cloudinary, and you will be ready for media delivery migration afterward.

URL Endpoint

Ensure you have a URL endpoint connected to the storage you added to ImageKit in Step 1. At this step, if a file is accessible via Cloudinary, it should also become accessible via ImageKit.

Copy

<!-- Cloudinary URL without transformations -->
https://res.cloudinary.com/cloud_id/image/upload/rest-of-the-path.jpg

<!-- Corresponding ImageKit URL -->
https://ik.imagekit.io/imagekit_id/image/upload/rest-of-the-path.jpg

If this does not work, please check your origin configuration, debug the error, or contact support@imagekit.io to get this working before proceeding to the next steps.

Note that we are not using Cloudinary's versioning v1231245131 in the URL in the example above. You must either remove them from the URLs or use the Cloudinary URL rewriter, as explained below.

URL-based transformations

You have two options for transforming files using ImageKit URLs

Option 1 - Using Cloudinary URL Rewriter

Suppose you do not want to change the URL and want to continue using the Cloudinary transformations and versioning that appears in the URL. In that case, you should enable the Cloudinary URL Rewriter for your endpoint. This can be enabled under the "Advanced Settings" tab of the URL endpoint. Also, if you added a Cloudinary backup bucket with res/<cloud_id/ as the Bucket folder, check the "Keep Cloudinary asset and delivery types" setting while enabling the rewriter.

The transformations supported by the URL rewriter, how they work, and the impact of this "Keep asset and delivery type" setting have been explained here.

If you opt for this, your URL will look like this.

Copy

<!-- URL with Cloudinary transformations -->
https://ik.imagekit.io/your_imagekit_id/image/upload/w_200,h_300,f_auto,q_auto/rest-of-the-path.jpg

Option 2 - Using ImageKit Transformations

You can use ImageKit's transformation parameters in the URL. While this requires a URL change, it guarantees that all possible transformations will work, not just the ones supported in the URL rewriter. If you opt for this, your URL will look like this.

Copy

<!-- With transformations in path -->
https://ik.imagekit.io/your_imagekit_id/image/upload/tr:w-200,h-300/v1233223113/rest-of-the-path.jpg

<!-- With transformations in query -->
https://ik.imagekit.io/your_imagekit_id/image/upload/v1233223113/rest-of-the-path.jpg?tr=w-200,h-300

Unlike Cloudinary, ImageKit can automatically compress and convert the media file to the correct format without having any parameters in the URL. That is why the ImageKit transformation URLs above don't have any format or quality parameters. Read more about it here.

Setup a custom domain name

All ImageKit paid plans offer a custom domain name. You may or may not use one with Cloudinary, but we recommend setting it up in ImageKit.

With the domain set up, your URL will look like this.

Copy

<!-- URL with Cloudinary transformations + ImageKit Cloudinary URL Rewriter -->
https://media.yourdomain.com/image/upload/w_200,h_300,f_auto,q_auto/rest-of-the-path.jpg

<!-- URL with ImageKit transformations in path -->
https://media.yourdomain.com/image/upload/tr:w-200,h-300/rest-of-the-path.jpg

<!-- URL with ImageKit transformations in query -->
https://media.yourdomain.com/image/upload/rest-of-the-path.jpg?tr=w-200,h-300

As you can see above, with the Cloudinary URL rewriter enabled in ImageKit, the URL looks exactly like what you would have on Cloudinary. This means that, in many cases, after the right setup, moving to ImageKit would be as simple as a DNS switch.

To have no impact on your production setup with Cloudinary, we recommend setting up a domain name parallel to the one you use with Cloudinary. For example, if you use media.yourwebsite.com with Cloudinary, get media2.yourwebsite.com set up with ImageKit. This allows you to test and compare URLs in parallel. Once tested, you can always switch the DNS for even the old domain media.yourwebsite.com to get it to work with ImageKit.

Test and make the switch

Now, you should be able to access existing assets stored in Cloudinary through ImageKit.

At this stage, you should test the following.

Is the image or video accessible using Cloudinary now also accessible using ImageKit, just by changing res.cloudinary.com/cloud_id in the URL with ik.imagekit.io/your_imagekit_id or with the custom domain?
Does the transformation with ImageKit's Cloudinary URL rewriter give you the same output image as the original Cloudinary transformation?
Have you removed Cloudinary's versioning parameter from the URLs or enabled the Cloudinary URL rewriter?

Once you are confident that ImageKit is serving your assets correctly, you can either:

Replace res.cloudinary.com/cloud_id with ik.imagekit.io/your_imagekit_id or the custom domain name set up in ImageKit in your application code.
If you use a custom domain with Cloudinary, update your DNS to point to your existing domain to ImageKit. This ImageKit support team or your point of contact at ImageKit will give you this DNS change. This option requires no changes in your application code.

Switch new asset uploads

Once you have switched the delivery of existing assets on Cloudinary to ImageKit, you should see a decrease in bandwidth output from your Cloudinary account.

We now need to change the asset uploads.

If you upload assets to Cloudinary, either using their dashboard or Cloudinary's APIs, you will switch to uploading new assets to ImageKit Media Library, the integrated DAM, via the dashboard or the upload APIs.

This will ensure that for new assets, ImageKit gets the original asset from its own DAM, and does not go to your connected storage in Step 1.

If you use an external object storage like AWS S3 with Cloudinary and continue to do the same with ImageKit, then this step is optional if your team wishes to use ImageKit's Digital Asset Management capabilities.

Migrate old assets from Cloudinary

With the number of assets now constant in the Cloudinary media library, we can now move the remaining assets from Cloudinary to ImageKit DAM. There are a few ways to do it -

Using imagekit cli - This CLI is easy to configure and use. It downloads files from Cloudinary and uploads them to ImageKit DAM.
Do It Yourself - You can write a script to download files from Cloudinary and upload them to ImageKit DAM using APIs. We recommend this method only if you have to migrate some metadata or tags from Cloudinary to ImageKit or have any other requirement that the CLI does not fulfill.

After this step is completed, ImageKit will get all the assets from its own DAM instead of from the connected external storage. This means that you should not see any new storage or bandwidth usage on your Cloudinary account, and all assets on your website or app should be served via ImageKit after this step.

Cloudinary URL Rewriter specification

The Cloudinary URL Rewriter automatically understands Cloudinary transformations and versioning in the URL and either removes them or translates them internally to ImageKit equivalents. Using this, you don't have to change your Cloudinary URL and can still get the same transformations with ImageKit.

The following Cloudinary transformations are supported for translation:

Cloudinary transformation	Example translation	Remarks
width	`w_100` → `w-100`
height	`h_100` → `h-100`
aspect ratio	`ar_2.5` → `ar-2.5-1` `ar_3` → `ar-3-1` `ar_4:3` → `ar-4-3`
gravity	`g_north` → `fo-top` `g_center` → `fo-center` `g_auto` → `fo-auto` `g_face` → `fo-face`	Supported values: north south east west north_west north_east south_east south_west auto custom face
x	`x_100` → `x-100`
y	`y_100` → `y-100`
format	`f_jpg` → `f-jpg`	Supported values: auto jpg jpeg png webp gif avif
quality	`q_60` → `q-60` `q_auto` → `q-70` `q_auto:low` → `q-50`	Auto quality mapping (images): low: 50 eco: 60 good: 70 best: 86 Auto quality mapping (videos): low: 40 eco: 45 good: 50 best: 60
angle	`a_90` → `rt-90` `a_-67` → `rt-N67`
radius	`r_20` → `r-20` `r_20:30:40:50` → `r-20` `r_max` → `r-max`
effects	`e_blur` → `bl-1` `e_blur:500` → `bl-5` `e_grayscale` → `e-grayscale` `e_contrast:100` → `e-contrast` `e_sharpen:500` → `e-sharpen-5` `e_unsharp_mask:500` → `e-usm-0-5-1-0.05` `e_unsharp_mask:250` → `e-usm-0-2.5-1-0.05` `e_trim` → `t-true` `e_trim:20` → `t-20` `e_trim:20:red` → `t-20`	Supported values: blur grayscale contrast sharpen unsharp_mask trim The final output from ImageKit may vary from the output from Cloudinary.
border	`bo_5px_solid_red` → `b-5-red` `bo_5px_solid_BLUE` → `b-5-blue` `bo_5px_solid_rgb:AAAA54` → `b-5-AAAA54` `bo_5px_solid_rgb:AAAA54A9` → `b-5-AAAA5466` `bo_5px_solid_rgb:B4F` → `b-5-BB44FF` `bo_5px_solid_rgb:B4F9` → `b-5-BB44FF60`	Color values are case insensitive. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]
background	`b_red` → `bg-red` `b_BLUE` → `bg-blue` `b_rgb:AAAA54` → `bg-AAAA54` `b_rgb:AAAA54A9` → `bg-AAAA5466` `b_rgb:B4F` → `bg-BB44FF` `b_rgb:B4F9` → `bg-BB44FF60` `b_blurred` → `bg-blurred` `b_blurred:100` → `bg-blurred_5` `b_blurred:100:10` → `bg-blurred_5_25`	Color values are case insensitive. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99] `b_blurred` for blurred background with automatic blur-intensity. `b_blurred[:BlurIntensity][:Brightness]` for customized blur-intensity & brightness, blur-intensity is accepted in the range 0 to 2000, and brightness is accepted in the range -300 to 100 (negative value for darker background & positive value for lighter background)
colorize	`co_red` → `otc-red` `co_BLUE` → `otc-blue` `co_rgb:AAAA54` → `otc-AAAA54` `co_rgb:AAAA54A9` → `otc-AAAA5466` `co_rgb:B4F` → `otc-BB44FF` `co_rgb:B4F9` → `otc-BB44FF60`	Only supported in the context of text overlays. Color values are case insensitive. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]
DPR	`dpr_3.0` → `dpr-3.0`
crop	`c_crop` → `cm-extract` `c_fill` → `c-maintain_ratio` `c_fit` → `c-at_max` `c_pad` → `cm-pad_resize` `c_scale` → `c-force`	Supported values: crop fill fit pad scale
text overlays	`l_text:Roboto_50:<value>` → `ot-<value>,otf-Roboto,ots-50` `l_text:Roboto_50_bold_left:<value>` → `ot-<value>,otf-Roboto,ots-50,ott-b,otia-left` `l_text:<fontPath>_50_bold_left:<value>` → `ot-<value>,otf-<fontPath>,ots-50,ott-b,otia-left`	Supported text style qualifiers: bold italic left right center start end Custom fonts can be used by specifying the full path to a font file in your Media Library
image overlays	`l_<imagePath>` → `oi-<imagePath>`	Full path to the overlaid image in the Media Library must be specified
named transform	`t_<transform_name>` → `n-<transform_name>`	ImageKit does not translate the actual underlying transformations associated with your named transforms. They must be manually translated and added in your ImageKit dashboard while retaining the same name.
fl_progressive	`fl_progressive` → `pr-true` `fl_progressive:steep` → `pr-true` `fl_progressive:semi` → `pr-true` `fl_progressive:none` → `pr-false`
fl_layer_apply		Marks the end of a group of transformations being applied in the context of an overlay. ImageKit detects the presence of a `fl_layer_apply` and applies the relevantly positioned transforms to the overlaid asset instead of the main asset.
start offset	`so_10.5599` → `so-10.56`
end offset	`eo_10.5522` → `eo-10.55`
duration	`du_10.5500` → `du-10.55`
zoom	`z_2.0` → `z-2.0` `z_0.5` → `z-0.5`
default image	`d_notfound.png` → `di-notfound.png`

Note: The rewriter will silently ignore any transformation with a valid key but an invalid value. For example, h_100,w_<invalid>/a_90 will be translated to h-100:rt-90. Refer to the table to see what constitutes a valid value for different transforms.

Asset and Delivery type setting in Cloudinary URL Rewriter

When you have /image/upload in the Cloudinary URL, these are the asset (image) and the delivery types (upload). If you enable the "Keep Cloudinary asset and delivery types" setting, then ImageKit will forward /image/upload, /video/upload, etc., as it appears in the URL, to the external storage connected to ImageKit. With this setting disabled, ImageKit removes /image/upload/, /video/upload, etc., from the URL before forwarding the remaining file path to the external storage. Disabling it is useful when you have an external storage that does not have these folders or if you have connected the Cloudinary backup bucket with the Bucket folder as res/<cloud_id>/image/upload, etc., as mentioned here.

Migrate from Cloudinary to ImageKit

Basic steps for migration

Connect your storage to ImageKit

Using Cloudinary Backup Bucket

Using a cloud storage

Using a Web Server

Set up ImageKit for Media Delivery

URL Endpoint

URL-based transformations

Option 1 - Using Cloudinary URL Rewriter

Option 2 - Using ImageKit Transformations

Setup a custom domain name

Test and make the switch

Switch new asset uploads

Migrate old assets from Cloudinary

Cloudinary URL Rewriter specification

Asset and Delivery type setting in Cloudinary URL Rewriter