Last Updated:

Image processing with CarrierWave

CarrierWave is the crown jewel for managing uploaded files in a Rails application, in this tutorial we will look at the process of uploading and processing images.

Now suppose we want to have an app where users can upload images and display them in a gallery.


The first thing we need to do is create a new rails project to which we will add image loading and processing functions, so launch a terminal window and run the following command:

$> rails new your_proyect_name

If you already have a created project you can skip this step.

Go to the project directory and open it in your favorite text editor, open Gemfile, go to the end of the file and add a carrier stone there.

gem 'carrierwave'

Once you've added a gem to your Gemfile, go back to the terminal window and run the bundle command to install the gem.


Now let's create a scaffold resource to add carrierwave functionality, in your terminal window, run the following command:

$> rails g scaffold your_scaffold title:string description:text image:string

This command will create the necessary files and folders to work with us. When we have the scaffold resource, it's time to check it in our browser, in a terminal window run the following command.

$> rails s

To get the last prompt, open your browser and go to: localhost: 3000 If you don't get any errors, it's time to run our migrations to create the necessary tables in our database, so go back to the terminal window and run the following:

$> rake db:migrate


After migrating our database, we need to create a bootloader with the following command.

$> rails g uploader your_uploader

This command will create a folder in your application's directory called "downloaders" and inside that folder you'll find the bootloader class you created, open the bootloader in a text editor, and see that this file already has some code, and it comes with pretty good documentation on how you can configure it, but for the purposes of this tutorial we can leave it as it is. Now open your Image model to mount the bootloader:

#This should go in your model
mount_uploader :image, YourUploaderClass


Add this line under your attr_accessible call, and it should be all you need to add to your model to make the complete model code look like this.

class Image < ActiveRecord::Base
attr_accessible :description, :image, :title
mount_uploader :image, ImagesUploader



Navigate to the views folder and open the "new.html.erb" file created by the scaffold, edit the following line here and include the form to upload the files.

<%= form_for(@image) do | f| %>

Thus, the edited line should look like this:


<%= form_for @image, html: { multipart: true } do | f| %>


Replace "text field" with "file field", save the file and navigate to your "show.html.erb"

Image display

When you find yourself in the show template, look for the following line:

<%= @image.image %>

And replace that with this:

<%= @image.image_url %>

One little gotcha is that when no image is saved to the database this will return nil, so you might want to convert the 'image_url' to a string with a call to the 'to_s' method.


Once that's done, it's time to give it a try, so start your rails server and navigate to "localhost: 3000/images/new" here, upload an image, and make sure everything works as expected.

Now that you've uploaded the image, you'll notice that in the index template, it still shows a simple URL to the image, so it's time to make the thumb version of the image.

Installing ImageMagick

Now, if you're working on a Mac, it will make your life a lot easier if you have "homebrew" installed, just run the following command:

$> brew install imagemagick

If you're following this tutorial on other than Mac you can find the documentation on ImageMagick here:ImageMagick

Go, grab a cup of coffee or beer if you want, and wait until it's over.

Once we've installed ImageMagick, navigate to the download file and uncomment the following line:

include CarrierWave::MiniMagick

This will give us an ImageMagick wrapper for ruby, I recommend the mini magic as it gives us access to a set of helper methods to manipulate the images very easily, so after removing the comment, add this code snippet to the loader file.

This will process the uploaded image and resize it to the specified sizes.

Display your thumb

Open the index.html.erb file and locate this line:

<%= image.image %>

And add a url method that passes the version you want to display, in our case it's the thumb, for example:

<%= image_tag image.image_url(:thumb) %>

Final stage

Open your gem file again and add gemstone mini_magick under the carrierwave gemstone:

gem "mini_magic"

Go back to the terminal window and run the bundle command to install the gem, after the installation finishes the installation, go to "localhost: 3000 /images/new" and upload the image, if everything went well, you should see your uploaded image. hope you liked the show template and the enlarged version of the image in the index template.