Skip to content
File Attachment toolkit for Ruby applications
Ruby JavaScript Other
Branch: master
Clone or download
janko Stop testing with Aws::S3::Encryption::Client
It seems that doesn't work with an
Aws::S3::Encryption::Client anymore in newer aws-sdk-s3 versions, so we
stop testing for this.

We might eventually add support for client-side encryption, but it will
most likely be in a separate gem.
Latest commit 15bd632 Dec 10, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Set up sponsorship button Nov 6, 2019
demo Rename "processing up front" to "eager processing" Nov 21, 2019
lib Make remove_invalid plugin work with derivatives Dec 10, 2019
website Titleize "Securing Uploads" guide Dec 10, 2019
.gitignore Switch website and docs to Docusaurus (#419) Oct 14, 2019
.travis.yml Remove unused `sudo: false` from Travis config (#416) Oct 1, 2019
Brewfile Make remove_invalid plugin work with derivatives Dec 10, 2019 Update recommended self-contained example template Oct 19, 2019
Dockerfile Switch website and docs to Docusaurus (#419) Oct 14, 2019
Rakefile Switch website and docs to Docusaurus (#419) Oct 14, 2019
shrine.gemspec Bump down gem to 5.0 Sep 26, 2019


Shrine logo: a red paperclip

Shrine is a toolkit for handling file attachments in Ruby applications. Some highlights:

If you're curious how it compares to other file attachment libraries, see the Advantages of Shrine. Otherwise, follow along with the Getting Started guide.


Resource URL
Website & Documentation
Demo code Roda / Rails
Help & Discussion


Add the gem to your Gemfile:

# Gemfile
gem "shrine", "~> 3.0"

Then add config/initializers/shrine.rb which sets up the storage and loads ORM integration:

require "shrine"
require "shrine/storage/file_system"

Shrine.storages = {
  cache:"public", prefix: "uploads/cache"), # temporary
  store:"public", prefix: "uploads"),       # permanent

Shrine.plugin :activerecord           # loads Active Record integration
Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files

Next, add the <name>_data column to the table you want to attach files to. For an "image" attachment on a photos table this would be an image_data column:

$ rails generate migration add_image_data_to_photos image_data:text

Now create an uploader class (which you can put in app/uploaders) and register the attachment on your model:

class ImageUploader < Shrine
  # plugins and uploading logic
class Photo < ActiveRecord::Base
  include ImageUploader::Attachment(:image) # adds an `image` virtual attribute

In our views let's now add form fields for our attachment attribute that will allow users to upload files:

<%= form_for @photo do |f| %>
  <%= f.hidden_field :image, value: @photo.cached_image_data %>
  <%= f.file_field :image %>
  <%= f.submit %>
<% end %>

When the form is submitted, in your controller you can assign the file from request params to the attachment attribute on the model:

class PhotosController < ApplicationController
  def create
    Photo.create(photo_params) # attaches the uploaded file
    # ...


  def photo_params

Once a file is uploaded and attached to the record, you can retrieve the file URL and display it on the page:

<%= image_tag @photo.image_url %>

See the Getting Started guide for further documentation.


Shrine was heavily inspired by Refile and Roda. From Refile it borrows the idea of "backends" (here named "storages"), attachment interface, and direct uploads. From Roda it borrows the implementation of an extensible plugin system.

Similar libraries

  • Paperclip
  • CarrierWave
  • Dragonfly
  • Refile
  • Active Storage

Code of Conduct

Everyone interacting in the Shrine project’s codebases, issue trackers, and mailing lists is expected to follow the Shrine code of conduct.


The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.