Understand how file attachments work in a legacy Rails app that still uses Paperclip.
Follow the official migration guide to move a Paperclip-based Rails app to ActiveStorage.
Use the kt-paperclip community fork to get bug fixes for a project that cannot migrate immediately.
Learn how file attachment libraries handle image resizing, storage backends, and URL generation in Rails.
Deprecated, use Rails ActiveStorage for new projects, ImageMagick must be installed separately for image resizing.
Paperclip was a Ruby library for attaching files to database records in web applications built with Ruby on Rails. The idea was to treat uploaded files like any other piece of data, so you could attach a profile photo to a user or a PDF to an invoice with just a few lines of configuration. Files were not written to disk until the database record itself was saved, which kept the behavior consistent with how other fields work in the Rails data layer. Beyond basic uploads, Paperclip could automatically resize images into multiple sizes, called "styles," using ImageMagick, a widely available image-processing tool. For example, you might define a "thumb" and a "medium" version of every uploaded photo, and Paperclip would generate both on upload. It also validated files by size, type, and actual content, catching attempts to upload files that claimed to be images but were actually something else entirely. Files could be stored locally on the server's filesystem or sent to a cloud storage service. The library generated URLs for stored files based on a configurable template, and included helper methods that made it straightforward to display images or link to downloads from HTML views. Setting it up in a Rails project required adding a few extra columns to a database table, one declaration on the model, and a file input in the form. The library handled the rest: saving the file, cleaning up when the record was deleted, and building the correct path for each attachment style. As of today, this project is no longer actively maintained. The original team at thoughtbot officially deprecated Paperclip and recommends that new Rails projects use ActiveStorage, which ships as part of Rails itself. For existing projects still relying on Paperclip, the team wrote a migration guide available in both English and Spanish, and a community-maintained fork called kt-paperclip continues to accept bug reports. No new pull requests to the original repository are being accepted. The full README is longer than what was shown.
← thoughtbot on gitmyhub — every repo by this author, as a profile.
Verify against the repo before relying on details.