Paperclip (Not Updated)


Note: Please refer to Installing Rails Gems or Plugins for documentation on generic ways of installing a gem and including it in your rails application.

Gem Name: paperclip
Author: Thoughtbot
Source: GitHub [2]


  • imagemagick


Paperclip default implementation (using local storage) relies on a model which should have some special columns in the database:

Supposing you have the following example case:

# id: integer
# title: string
# price: integer
# created_at: datetime
# updated_at: datetime
class Shirt < ActiveRecord::Base
  validates_presence_of :price, :title

And you want to add a "logo" to the shirt, you'll need to create a new migration:

Special Columns for Paperclip Attachment

script/generate migration add_logo_to_shirt

Then add the following columns:

  class AddLogoToShirt < ActiveRecord::Migration
    def self.up
      add_column :users, :logo_file_name,    :string
      add_column :users, :logo_content_type, :string
      add_column :users, :logo_file_size,    :integer
      add_column :users, :logo_updated_at,   :datetime

    def self.down
      remove_column :users, :logo_file_name
      remove_column :users, :logo_content_type
      remove_column :users, :logo_file_size
      remove_column :users, :logo_updated_at

Model Code

And add the following to the model at minimum:

class Shirt < ActiveRecord::Base
  validates_presence_of :price, :title
  has_attached_file :logo

How to store an attachment

That's all! You'll now be able to store an attachment using the following code:

## In your controller
class ShirtsController < ActionController::Base
  def create
    @shirt = Shirt.create(params[:shirt])
    redirect_to shirts_path

## In the view

<% form_for @shirt, :html => { :multipart => true } do |shirt| %>
  <%= shirt.file_field :logo %>
<% end %>

Use the uploaded attachment

## In order to see the actual uploaded logo:

<%= @shirt.logo.url %>

Understanding paperclip

Most use cases aren't as simple as this one, but paperclip already offers a variety of options that we can use to adapt it to our needs. For example you might want to store a thumbnail of an uploaded picture as well as the original version. You can use the :styles option in the model to let paperclip use it's processors to resize the image:

class Shirt < ActiveRecord::Base
  validates_presence_of :price, :title
  has_attached_file :logo, :styles => {:thumbnail => "150x150" }

See the string next to :thumbnail? It reads "150x150", this is a valid ImageMagick Image Geometry so you might want to check that page for more info.

You can also define your own paperclip processors, for example if you want to crop an image TODO.

Paperclip's magic resides on the virtual attribute name you give to the attachment. In the example above, that virtual attribute is :logo. I can access different paperclip options via @shirt.logo, for example if I wanted to use the thumbnail of a logo instead of the original picture:


I could use the url method and pass it a symbol representing the actual style I want to use.

It's very recommended to check the official documentation and wiki to find out a lot more on paperclip.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License