CarrierWave

This gem provides a simple and extremely flexible way to upload files from Ruby applications. It works well with Rack based web applications, such as Ruby on Rails.

Information

• RDoc documentation available on RubyDoc.info
• Source code available on GitHub
• More information, known limitations, and how-tos available on the wiki

Getting Help

• Please ask the community on Stack Overflow for help if you have any questions. Please do not post usage questions on the issue tracker.
• Please report bugs on the issue tracker but read the "getting help" section in the wiki first.

Installation

Install the latest release:

$ gem install carrierwave

In Rails, add it to your Gemfile:

gem 'carrierwave', '~> 3.0'

Finally, restart the server to apply the changes.

Supported Ruby and Rails versions

Each release is tested against the versions below. The gemspec only states a minimum, so Bundler will happily install an old CarrierWave alongside a Rails newer than it has ever seen — which is how a patch-level upgrade ends up failing at boot. Check this table when upgrading Rails.

CarrierWave	Rails	Ruby
4.0	7.0 – 8.1	>= 2.7
3.1	6.0 – 8.0	>= 2.5
3.0	6.0 – 7.1	>= 2.5
2.2	5.0 – 6.1	>= 2.2.2

Only the latest release gets fixes; older lines are listed so you can tell whether your combination was ever supported.

Upgrading from 2.x or earlier

CarrierWave 3.0 comes with a change in the way of handling the file extension on conversion. This results in following issues if you use process convert: :format to change the file format:

• If you have it on the uploader itself (not within a version), the file extension of the cached file will change. That means if you serve both CarrierWave 2.x and 3.x simultaneously on the same workload (e.g. using blue-green deployment), a cache file stored by 2.x can't be retrieved by 3.x and vice versa.
• If you have it within a version, the file extension of the stored file will change. You need to perform #recreate_versions! to make it usable again.

To preserve the 2.x behavior, you can set force_extension false right after calling process convert: :format. See #2659 for the detail.

Getting Started

Start off by generating an uploader:

rails generate uploader Avatar

this should give you a file in:

app/uploaders/avatar_uploader.rb

Check out this file for some hints on how you can customize your uploader. It should look something like this:

class AvatarUploader < CarrierWave::Uploader::Base
  storage :file
end

You can use your uploader class to store and retrieve files like this:

uploader = AvatarUploader.new

uploader.store!(my_file)

uploader.retrieve_from_store!('my_file.png')

CarrierWave gives you a store for permanent storage, and a cache for temporary storage. You can use different stores, including filesystem and cloud storage.

Most of the time you are going to want to use CarrierWave together with an ORM. It is quite simple to mount uploaders on columns in your model, so you can simply assign files and get going:

ActiveRecord

Make sure you are loading CarrierWave after loading your ORM, otherwise you'll need to require the relevant extension manually, e.g.:

require 'carrierwave/orm/activerecord'

Add a string column to the model you want to mount the uploader by creating a migration:

rails g migration add_avatar_to_users avatar:string
rails db:migrate

Open your model file and mount the uploader:

class User < ApplicationRecord
  mount_uploader :avatar, AvatarUploader
end

Now you can cache files by assigning them to the attribute, they will automatically be stored when the record is saved.

u = User.new
u.avatar = params[:file] # Assign a file like this, or

# like this
File.open('somewhere') do |f|
  u.avatar = f
end

u.save!
u.avatar.url # => '/url/to/file.png'
u.avatar.current_path # => 'path/to/file.png'
u.avatar_identifier # => 'file.png'

Note: u.avatar will never return nil, even if there is no photo associated to it. To check if a photo was saved to the model, use u.avatar.file.nil? instead.

DataMapper, Mongoid, Sequel

Other ORM support has been extracted into separate gems:

• carrierwave-datamapper
• carrierwave-mongoid
• carrierwave-sequel

There are more extensions listed in the wiki

Multiple file uploads

CarrierWave also has convenient support for multiple file upload fields.

ActiveRecord

Add a column which can store an array. This could be an array column or a JSON column for example. Your choice depends on what your database supports. For example, create a migration like this:

This is the beginning of the README. Read the rest at the original. Read the full README ↗