1. Code
  2. Ruby on Rails

Uploading With Rails and Carrierwave


This is another article in the "Uploading with Rails" series. Today we are going to meet Carrierwave—one of the most popular file uploading solutions for Rails. I like Carrierwave because it is easy to get started, it has lots of features out of the box, and it provides dozens of "how to" articles written by the members of the community, so you won't get lost.

In this article, you will learn how to:

  • Integrate Carrierwave into your Rails app
  • Add validations
  • Persist files across requests
  • Remove files
  • Generate thumbnails
  • Upload files from remote locations
  • Introduce multiple file uploads
  • Add support for cloud storage

The source code for this article is available on GitHub. Enjoy reading!

Laying the Foundations

As always, start by creating a new Rails application:

For this demo I'll be using Rails 5.0.2. Please note that Carrierwave 1 supports only Rails 4+ and Ruby 2. If you are still riding on Rails 3, then hook up Carrierwave version 0.11.

To see Carrierwave in action, we are going to create a very simple blogging application with a sole Post model. It will have the following main attributes:

  • title (string)
  • body (text)
  • image (string)—this field is going to contain an image (a file's name, to be precise) attached to the post

Generate and apply a new migration:

Set up some routes:


Also, create a very basic controller:


Now let's craft the index view:


And the corresponding partial:


Here I am using the Rails truncate method to display only the first 150 symbols from the post. Before we create other views and a form partial, let's firstly integrate Carrierwave into the application.

Integrating Carrierwave

Drop in a new gem into the Gemfile:



Carrierwave stores its configuration inside uploaders that are included into your models. To generate an uploader, use the following command:

Now, inside app/uploaders, you will find a new file called image_uploader.rb. Note that it has some useful comments and examples, so you may use it to get started. In this demo we will use ActiveRecord, but Carrierwave also has support for Mongoid, Sequel, and DataMapper.

Next, we need to include or mount this uploader into the model:


The uploader already has sane default settings, but at the very least we need to choose where the uploaded files will be stored. For now, let's employ file storage:


By default, files will be placed inside the public/uploads directory, so it is best to exclude it from the version control system:


You may also modify the store_dir method inside your uploader to choose some other location.

At this point, we can create a new view and a form partial to start uploading files:



Note that the PostsController does not need to be modified as we already permitted the image attribute.

Lastly, create the edit view:


That's it! You may boot the server and try to create a post with an image. The problem is that this image is not visible anywhere, so let's proceed to the next section and add a show page!

Displaying Images

So, the only view we have not created yet is show. Add it now:


As you can see, displaying an attachment is really easy: all you need to do is say @post.image.url to grab an image's URL. To get a path to the file, use the current_path method. Note that Carrierwave also provides an image? method for us to check whether an attachment is present at all (the image method itself will never return nil, even if the file is not present).

Now, after navigating to a post, you should see an image, but it might appear too big: after all, we are not restricting dimensions anywhere. Of course, we could have scaled the image down with some CSS rules, but it is much better to generate a thumbnail after the file has been uploaded. This, however, requires some additional steps.

Generating Thumbnails

In order to crop and scale images, we need a separate tool. Out of the box Carrierwave has support for RMagick and MiniMagick gems that, in turn, are used to manipulate images with the help of ImageMagick. ImageMagick is an open-source solution allowing you to edit existing images and generate new ones, so before proceeding you need to download and install it. Next, you are free to pick either of the two gems. I'll stick with MiniMagick, because it is much easier to install and it has better support: 



Then include MiniMagick into your uploader:


Now we simply need to introduce a new version to our uploader. The concept of versions (or styles) is used in many file uploading libraries; it simply means that additional files based on the original attachment will be created with, for example, different dimensions or formats. Introduce a new version called thumb:


You may have as many versions as you like and, what's more, versions can even be built on top of other ones:


If you have already uploaded some images, they won't have thumbnails available. This is not a problem, though, as you can re-create them from the Rails console:

Lastly, display your thumbnail with a link to the original image:


Boot the server and observe the result!

Adding Validations

Currently our uploading works, but we're not validating user input at all, which is, of course, bad. As long as we want to work only with images, let's whitelist .png, .jpg and .gif extensions:


You may also add content type checks by defining a content_type_whitelist method:


Alternatively, it is possible to blacklist some file types, for example executables, by defining the content_type_blacklist method.

Apart from checking a file's type and extension, let's enforce it to be less than 1 megabyte. To do it, we'll require an additional gem supporting file validations for ActiveModel:


Install it:

Now introduce the desired validations (note that I am also adding checks for the title and body attributes):


The next thing to do is to add I18n translations for Carrierwave's error messages:


Currently, we do not display validation errors anywhere, so let's create a shared partial:


Employ this partial inside the form:


Now try to upload some invalid files and observe the result. It should work, but if you choose a valid file and do not fill in the title or body, then the checks will still fail and an error will be displayed. However, the file field will be cleared out and the user will need to choose the image again, which is not very convenient. To fix it, we need to add another field to the form.

Persisting Files Across Requests

Persisting files across form redisplays is actually quite easy. All you need to do is add a new hidden field and permit it inside the controller:



Now the image_cache will be populated automatically and the image won't be lost. It may be helpful to display a thumbnail as well so that user understands the image was processed successfully: 


Removing Images

Another very common feature is the ability to remove attached files when editing a record. With Carrierwave, implementing this feature is not a problem. Add a new checkbox to the form:


And permit the remove_image attribute:


That's it! To remove an image manually, use the remove_image! method:

Uploading From a Remote Location

Carrierwave also provides a very cool feature out of the box: the ability to upload files from remote locations by their URL. Let's introduce this ability now by adding a new field and permitting the corresponding attribute: 



How cool is that? You don't need to make any changes at all, and you can test this feature right away!

Working With Multiple Uploads

Suppose we want our post to have multiple attachments available. With the current setup it is not possible, but luckily, Carrierwave supports such a scenario as well. To implement this feature, you need to add either a serialized field (for SQLite) or a JSON field (for Postgres or MySQL). I prefer the latter option, so let's switch to a new database adapter now. Remove the sqlite3 gem from the Gemfile and add pg instead:


Install it:

Modify the database configuration like this:


Create the corresponding Postgres database, and then generate and apply the migration:

If you prefer to stick with SQLite, follow the instructions listed in Carrierwave's documentation.

Now mount the uploaders (note the plural form!):


I am using the same uploader for attachments, but of course you can generate a new one with a different configuration.

Add the multiple file field to your form:


As long as the attachments field is going to contain an array, it should be permitted in the following way:


Lastly, you may iterate over the post's attachments and display them as usual:


Note that each attachment is going to have a thumbnail as configured in our ImageUploader. Nice!

Using Cloud Storage

Sticking with file storage is not always convenient and/or possible as, for example, on Heroku it is not possible to store custom files. Therefore you might ask how to marry Carrierwave with Amazon S3 cloud storage? Well, that's a pretty easy task as well. Carrierwave depends on the fog-aws gem to implement this feature:


Install it:

Let's create an initializer for Carrierwave and configure the cloud storage globally:


There are some other options available, which can be found in the documentation.

I am using the dotenv-rails gem to set the environment variables in a secure way, but you may choose any other option. However, make sure that your S3 key pair is not available publicly, because otherwise anyone can upload anything to your bucket!

Next, replace the storage :file line with:


Apart from S3, Carrierwave supports uploads to Google Storage and Rackspace. These services are easy to set up as well.


This is it for today! We have covered all the major features of Carrierwave, and now you can start using it in your projects. It has some additional options available, so do browse the documentation.

If you are stuck, don't hesitate to post your questions. Also, it might be useful to take a peek into Carrierwave's wiki, which hosts useful "how to" articles answering many common questions.

So I thank you for staying with me, and happy coding!

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.