CarrierWave — File Upload Library for Ruby

Introduction

CarrierWave provides a clean, modular approach to file uploads in Ruby applications. Rather than scattering upload logic across models and controllers, CarrierWave encapsulates upload behavior in uploader classes that define storage locations, file processing steps, and validation rules. It works with Rails, Sinatra, and any Rack-based framework.

What CarrierWave Does

• Mounts file upload columns on ActiveRecord, Mongoid, or Sequel models with a single declaration
• Stores files on the local filesystem, AWS S3, Google Cloud Storage, or Azure Blob Storage via a swappable storage backend
• Processes uploaded images with MiniMagick or libvips for resizing, cropping, and format conversion
• Generates multiple versions of each upload (thumbnail, medium, large) defined in the uploader class
• Validates file size, content type, and extension before persisting uploads

Architecture Overview

CarrierWave separates concerns into uploaders, storage backends, and model integrations. An uploader class inherits from CarrierWave::Uploader::Base and defines processing steps, version declarations, and storage configuration. When a file is assigned to a mounted column, CarrierWave runs the processing pipeline, stores the result through the configured backend, and saves the filename reference on the model. Storage backends are pluggable: the fog-aws gem handles S3, fog-google handles GCS, and the default stores files on the local filesystem. File retrieval reconstructs the URL from the stored filename and the backend configuration.

Self-Hosting & Configuration

• Add the gem and generate an uploader class with the Rails generator
• Configure the default storage backend (file or fog) in an initializer at config/initializers/carrierwave.rb
• Set cloud credentials and bucket names in the initializer or via environment variables for S3 or GCS
• Add MiniMagick or libvips processing by including the relevant module in your uploader class
• Set upload directory, cache directory, and allowed file extensions in the uploader

Key Features

• Clean DSL for declaring file versions with independent processing chains
• Swappable storage backends from local disk to any cloud provider supported by fog
• Built-in image processing with MiniMagick and libvips for resize, crop, and format conversion
• Conditional processing that runs different pipelines based on file type or model attributes
• Works with direct uploads and background processing for large files

Comparison with Similar Tools

• Active Storage — built into Rails 5.2+; simpler but less flexible for custom processing pipelines and version management
• Shrine — newer Ruby upload library with a plugin system; CarrierWave is more established with broader community support
• Paperclip — deprecated in favor of Active Storage; CarrierWave remains actively maintained
• Dragonfly — on-the-fly processing approach; CarrierWave pre-processes and stores versions
• Multer (Node.js) — middleware-based uploads for Express; CarrierWave offers a more integrated ORM-level solution

FAQ

Q: Can CarrierWave handle direct uploads to S3? A: Yes. Using the carrierwave_direct gem or presigned URLs, files upload directly from the browser to S3 without passing through the application server.

Q: How do I process uploads in the background? A: Use the carrierwave_backgrounder gem to defer processing to Sidekiq, Resque, or another background job framework.

Q: Does CarrierWave work with non-Rails Ruby applications? A: Yes. CarrierWave works with Sinatra, Grape, Hanami, and any Rack-based framework.

Q: How do I migrate from Paperclip to CarrierWave? A: Mount CarrierWave uploaders on the same columns, write a migration rake task to move files to the new directory structure, and update your forms and views.

Sources

• https://github.com/carrierwaveuploader/carrierwave
• https://www.rubydoc.info/gems/carrierwave