Programmable Media

Active Storage integration

Last updated: Apr-18-2024

Active Storage can be useful for integrating image uploads with your model. The Cloudinary gem enables you to enjoy the benefits of Active Storage for easily uploading images from HTML forms to your model, while enjoying the great benefits of Cloudinary: uploaded images are stored in the cloud, transformed in the cloud, and delivered automatically through a CDN.

The following documentation assumes you have already set up Active Storage within your Rails 6+ application, and teaches you how to configure Active Storage to work with Cloudinary for image uploads and image delivery.

Active Storage configuration

Declare the Cloudinary service in the config/storage.yml file by adding a new entry with a custom name (e.g., cloudinary) and the service configuration:

Tell Active Storage which service to use by setting Rails.application.config.active_storage.service. As each environment will likely use a different service, it is recommended to do this on a per-environment basis. For example, to use the cloudinary service in the development environment, you would add the following to config/environments/development.rb:

Direct uploads

Active Storage already supports uploading directly from the client to the cloud. After adding Cloudinary as a service, use direct uploading as usual:

  1. Include activestorage.js in your application's JavaScript bundle.

    Using the asset pipeline:

    Using the npm package:

  2. Annotate file inputs with the direct upload URL.

You cannot specify an upload preset or other upload parameters on a per-upload basis while using Active Storage. There are however two ways to globally specify upload parameters for all uploads:
  • As an upload preset (or upload parameters) in the Rails service configuration (as top-level parameters). You can create multiple service configurations (each with slightly different upload options specified) and switch between them for different use-cases.
  • As a default upload preset specified via the console which will be applied to all uploads without any extra code on the Rails side

Image delivery

Use the cl_image_tag method to generate an HTML image tag, or use the cloudinary_url method to generate a transformation URL. The methods can accept any Cloudinary Transformation URL API Reference for lazily transforming the image on delivery (as per all Cloudinary dynamic URLs). For example, to deliver a user's avatar image scaled down to 300x200 with the 'cartoonify' effect applied:


The variant method should not be used as it would try to create a new resource and upload it to Cloudinary, instead of letting Cloudinary handle the transformation. As such, the variant method is not needed or supported.
Cloudinary Academy


Check out our Introduction to Cloudinary for Ruby Developers course in the Cloudinary Academy. This self-paced resource provides video-based lessons, sample scripts and other learning material to get you going with Ruby and Cloudinary today.

✔️ Feedback sent!

Rate this page: