Cloudinary Ruby on Rails SDK

Upload, transform, optimize, and manage images and videos with Cloudinary from Ruby and Rails — the cloudinary gem on RubyGems.

Install

gem install cloudinary

Or add it to your Gemfile:

gem "cloudinary"

Quick start

Set your API environment variable (Console > Settings > API Keys):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

Upload an image and get an optimized delivery URL:

require "cloudinary"

result = Cloudinary::Uploader.upload(
  "https://res.cloudinary.com/demo/image/upload/sample.jpg",
  public_id: "quickstart-sample"
)
puts "Uploaded: #{result['public_id']}"

# Build a 400x400 auto-cropped URL with automatic format and quality
url = Cloudinary::Utils.cloudinary_url(
  result["public_id"],
  width: 400, height: 400, crop: "fill",
  gravity: "auto", fetch_format: "auto", quality: "auto"
)
puts "Optimized URL: #{url}"

Save as quickstart.rb and run ruby quickstart.rb. Create a free account if you don't have one — or run npx @cloudinary/cloud to provision one without signing up.

In Rails the same URL is a view helper: <%= cl_image_tag("quickstart-sample", width: 400, height: 400, crop: "fill") %>.

Common tasks

• Get Cloudinary credentials
• Configure Cloudinary
• Upload an image
• Upload a large video
• Sign a browser upload
• Transform and deliver an image
• Transform and deliver a video
• Search and manage assets
• Moderate an upload
• Use structured metadata
• Troubleshoot errors

Rails integration, which ships in this gem:

• Use with Rails — view helpers, cloudinary.yml, credentials
• Upload with Active Storage
• Upload with CarrierWave

Runnable versions live in examples/ — each is a complete file you can run directly.

When to use this SDK

Use this gem in Ruby and Rails server-side code: uploads, signed operations, asset administration, search, moderation, delivery URL generation, and Rails view helpers.

For other jobs, better-fitting tools exist:

• Browser or frontend framework rendering: the frontend SDKs (md).
• Complete in-browser upload UI: Upload Widget (md).
• Text-to-image generation and image-to-video: platform APIs (md), not wrapped by this gem.
• Multi-step media workflow automation: MediaFlows (md).
• Interactive agent-driven asset operations: Cloudinary MCP servers and Skills (md).

The full capability map — plus the Skills, MCP servers, and CLI worth setting up first — is in docs/platform-capabilities.md.

Status and compatibility

Stable, actively maintained. See CHANGELOG.md.

SDK version	Ruby	Rails
2.x	3.x, 4.x	6.1 and later
1.x	1.9.3 – 3.x (no longer maintained)	5.x – 7.x

CI covers Ruby 3.1, 3.2, 3.3, 3.4, and 4.0.

Documentation

• Bundled task docs — ship inside the gem, version-matched.
• Ruby on Rails SDK guide — the full documentation (md).

Documentation links in this README point at the browsable HTML page, with an (md) companion link that returns the same page as raw Markdown. Inside docs/ and examples/ the links are Markdown-only, since those files are written to be read by coding agents. Either form works for any page: add .md for Markdown, drop it for HTML.

For AI coding agents

• Contributing to this repo: read AGENTS.md.

• Using the installed gem: the docs in the gem's docs/ directory match your installed version and are the source of truth. Locate them with:

  ruby -e 'puts Gem::Specification.find_by_name("cloudinary").gem_dir + "/docs"'

  Start with platform-capabilities before assuming a feature exists.

Support

• SDK bugs and feature requests: GitHub issues
• Account and platform questions: Cloudinary support

Security

See SECURITY.md for private vulnerability reporting. Keep your api_secret in server-side code; for client uploads, use the server-signed pattern in Sign a browser upload.

License

Released under the MIT license — see LICENSE. Copyright (c) Cloudinary Ltd.