Paperclip gem en Ruby on Rails y Active Storage
La gema Paperclip (en inglés, paperclip gem) fue durante años la forma habitual de subir archivos en Ruby on Rails: fotos de perfil, portadas, PDF. Hoy está obsoleta, y lo que hace se resuelve con Active Storage, que forma parte de Rails. Este artículo explica las dos cosas: cómo se suben archivos ahora y qué hacer si tu proyecto aún usa Paperclip.
Adjuntar un archivo a un registro es como grapar una foto a una ficha de papel: la ficha (la fila de la base de datos) solo guarda una referencia, y la foto se guarda aparte, en una carpeta del servidor o en la nube.
Qué es la gema Paperclip de Rails y por qué está obsoleta
Paperclip es una gema de thoughtbot para adjuntar archivos a un modelo de Active Record. Declarabas has_attached_file :cover en el modelo, añadías cuatro columnas a la tabla y la gema se encargaba de guardar el archivo y de generar miniaturas con ImageMagick.
Cuando Rails 5.2 trajo su propia solución, Active Storage, thoughtbot dejó de desarrollar Paperclip. El README del repositorio oficial empieza con «Paperclip is deprecated» («Paperclip está obsoleta», traducción nuestra) y da tres indicaciones (resumen nuestro):
- Para proyectos nuevos, Active Storage.
- Para proyectos existentes, una guía de migración, también en español.
- Como alternativa, el fork
kt-paperclip, que mantiene la empresa Kreeti y adonde se derivan los informes de errores.
El repositorio está archivado desde el 13 de julio de 2023: es de solo lectura y no recibe correcciones. La última versión de kt-paperclip en RubyGems es la 8.0.1, de octubre de 2026.
Cómo funciona Active Storage
Active Storage es la parte de Rails que sube archivos y los asocia a tus modelos. Lleva la idea de la ficha y la foto hasta el final:
- Tu tabla no cambia. Active Storage guarda los datos del archivo en sus propias tablas:
active_storage_blobs(el archivo: nombre, tipo, tamaño, checksum),active_storage_attachments(qué archivo va con qué registro) yactive_storage_variant_records(las miniaturas generadas). - El archivo va a un servicio. En
config/storage.ymleliges dónde: el disco local en desarrollo y, en producción, un servicio en la nube como Amazon S3 o Google Cloud Storage. - El modelo solo declara el adjunto:
has_one_attachedpara un archivo yhas_many_attachedpara varios.
Subir archivos en Rails con Active Storage, paso a paso
Partimos de una aplicación creada con rails new. El objetivo: artículos con un título y una imagen de portada.
1. Instala Active Storage
bin/rails active_storage:install
bin/rails generate scaffold Article title:string cover:attachment
bin/rails db:migrate
La salida, resumida (sin las líneas del scaffold ni los tiempos de cada tabla):
Copied migration 20261109002245_create_active_storage_tables.active_storage.rb from active_storage
== 20261109002245 CreateActiveStorageTables: migrating ========================
-- create_table(:active_storage_blobs, {id: :primary_key})
-- create_table(:active_storage_attachments, {id: :primary_key})
-- create_table(:active_storage_variant_records, {id: :primary_key})
== 20261109002245 CreateActiveStorageTables: migrated (0.0077s) ===============
== 20261109002246 CreateArticles: migrating ===================================
-- create_table(:articles)
== 20261109002246 CreateArticles: migrated (0.0020s) ==========================
El tipo cover:attachment del generador no crea ninguna columna cover en articles: la migración de la tabla solo lleva title y las fechas. Las aplicaciones nuevas ya traen el servicio local configurado en config/storage.yml.
2. Declara el adjunto en el modelo
El scaffold deja el modelo con has_one_attached :cover. Le añadimos una validación para aceptar solo imágenes, porque Active Storage no trae validaciones de tipo ni de tamaño:
# app/models/article.rb
class Article < ApplicationRecord
has_one_attached :cover
validate :cover_debe_ser_imagen
private
def cover_debe_ser_imagen
return unless cover.attached?
return if cover.content_type.start_with?("image/")
errors.add(:cover, "debe ser una imagen")
end
end
has_one_attached es el equivalente del antiguo has_attached_file. Más adelante, en «Errores típicos», tienes qué protege esta validación y qué no.
3. Formulario y parámetros permitidos
El formulario usa file_field:
<%# app/views/articles/_form.html.erb (extracto) %>
<%= form_with(model: article) do |form| %>
<div>
<%= form.label :title %>
<%= form.text_field :title %>
</div>
<div>
<%= form.label :cover %>
<%= form.file_field :cover %>
</div>
<%= form.submit %>
<% end %>
Al ver un campo de archivo, Rails añade por sí solo el atributo enctype="multipart/form-data", que es lo que permite enviar archivos en un formulario. Así lo mostraba el inspector del navegador (el valor del token se ha omitido):
<form class="new_article" id="new_article" enctype="multipart/form-data" action="/articles" accept-charset="UTF-8" method="post">
<input name="utf8" type="hidden" value="✓">
<input type="hidden" name="authenticity_token" value="…">
<div class="field">…</div>
<div class="field">…</div>
<div class="field">…</div>
Ese HTML es de la versión de 2018; en Rails 8.1 el formulario sigue llevando ese atributo, como comprueba uno de los tests de más abajo.
En el controlador hay que permitir el parámetro cover. Rails 8 genera params.expect; en versiones anteriores verás params.require(:article).permit(:title, :cover), que hace lo mismo (más sobre esto en strong params en Ruby on Rails):
# app/controllers/articles_controller.rb (extracto)
def article_params
params.expect(article: [ :title, :cover ])
end
4. Muestra la imagen
<%# app/views/articles/_article.html.erb %>
<div id="<%= dom_id article %>">
<h2><%= article.title %></h2>
<% if article.cover.attached? %>
<%= image_tag article.cover.variant(resize_to_limit: [800, 600]), alt: article.title %>
<% end %>
</div>
variant(resize_to_limit: [800, 600]) sirve una copia reducida que cabe en 800 × 600 píxeles sin deformarse. Es lo que Paperclip llamaba styles, y lo ves con detalle en la sección siguiente.
5. Compruébalo con un test
Un test de integración hace lo mismo que una persona con el navegador: pide el formulario, sube un archivo y mira la página del artículo. Los archivos de prueba van en test/fixtures/files/. Puedes crear una imagen cualquiera con ImageMagick y un archivo de texto con echo:
magick -size 1600x1200 xc:skyblue test/fixtures/files/portada.png
echo "Esto no es una imagen" > test/fixtures/files/notas.txt
El test:
# test/integration/subir_portada_test.rb
require "test_helper"
class SubirPortadaTest < ActionDispatch::IntegrationTest
test "el formulario se envía como multipart" do
get new_article_path
assert_select "form[enctype=?]", "multipart/form-data"
end
test "sube una portada y la muestra en el artículo" do
post articles_path, params: {
article: { title: "Hola", cover: file_fixture_upload("portada.png", "image/png") }
}
article = Article.last
assert article.cover.attached?
assert_equal "portada.png", article.cover.filename.to_s
get article_path(article)
assert_select "img[alt=?][src*=?]", "Hola", "portada.png"
end
test "rechaza un archivo que no es una imagen" do
assert_no_difference("Article.count") do
post articles_path, params: {
article: { title: "Mal", cover: file_fixture_upload("notas.txt", "text/plain") }
}
end
assert_response :unprocessable_content
assert_select "li", "Cover debe ser una imagen"
end
end
bin/rails test test/integration
Running 3 tests in a single process (parallelization threshold is 50)
Run options: --seed 1598
# Running:
...
Finished in 0.269519s, 11.1309 runs/s, 40.8134 assertions/s.
3 runs, 11 assertions, 0 failures, 0 errors, 0 skips
Si es la primera vez que escribes tests en Ruby, empieza por la introducción al testing en Ruby.
Miniaturas: de los styles de Paperclip a las variantes
En Paperclip, los tamaños se declaraban en el modelo (styles: { thumb: "800x600>" }) y se generaban todos al subir el archivo. En Active Storage se piden en la vista con variant y se generan la primera vez que alguien las solicita; después se guardan y se reutilizan.
Para generar variantes, Active Storage necesita dos cosas:
- La gema
image_processing, que las aplicaciones nuevas de Rails 8.1 ya traen en elGemfile. - Un programa de imagen instalado en el sistema: libvips, que es el procesador por defecto con
config.load_defaults 8.1, o ImageMagick.
Si el servidor no tiene libvips, Rails lo avisa en el log al arrancar:
Using vips to process variants requires the libvips library. Please install libvips using the instructions on the libvips website.
Y al generar una variante falla con un error que no dice la causa:
NoMethodError: undefined method 'new' for nil
Tienes dos salidas: instalar libvips (sudo apt install libvips en Debian o Ubuntu, brew install vips en macOS) o, si el sistema ya tiene ImageMagick, decirle a Rails que lo use:
# config/application.rb
config.active_storage.variant_processor = :mini_magick
Con ese cambio, la variante de una portada de 1600 × 1200 sale con el tamaño esperado. Puedes comprobarlo desde bin/rails console:
variante = Article.first.cover.variant(resize_to_limit: [800, 600]).processed
blob = variante.image.blob
blob.analyze
blob.metadata.slice("width", "height")
# => {"width" => 800, "height" => 600}
Migrar de Paperclip a Active Storage paso a paso
La guía oficial de migración se escribió para Rails 5.2: copia los datos con SQL escrito a mano para cada base de datos y advierte de que en Rails 6.1 o superior hay que añadir la columna service_name. Los pasos de abajo siguen su orden, pero copian los archivos con attach, la API pública de Active Storage, como hace la propia guía para los archivos en la nube. Es una adaptación nuestra: funciona igual con SQLite, PostgreSQL o MySQL y no depende de la estructura interna de las tablas.
Se ha probado en una aplicación con kt-paperclip 8.0.1, un artículo con portada y el modelo de Paperclip que tienes más abajo.
- Haz una copia de seguridad de la base de datos y de los archivos.
- Instala Active Storage.
- Cambia el modelo a
has_one_attached. - Copia los archivos con una tarea rake.
- Actualiza vistas y tests.
- Borra las columnas de Paperclip y la gema.
1. Mientras tanto, pasa a kt-paperclip
Si la migración no puede hacerse ya, cambia la gema por el fork mantenido. En el Gemfile:
gem "kt-paperclip", "~> 8.0"
kt-paperclip es un fork mantenido del paperclip original de thoughtbot (Ruby 2.7 o superior y Rails 5.2 o superior, según su README). De él sale jr-paperclip (8.0.9, noviembre de 2026), que declara soporte para Rails 7.0, 7.1, 8.0 y 8.1 con Ruby 3.0 o superior.
2. Instala Active Storage
bin/rails active_storage:install
bin/rails db:migrate
Copied migration 20261109002603_create_active_storage_tables.active_storage.rb from active_storage
== 20261109002603 CreateActiveStorageTables: migrated (0.0078s) ===============
Las columnas de Paperclip (cover_file_name, cover_content_type, cover_file_size y cover_updated_at) siguen en la tabla. Las necesitas para el paso 4.
3. Cambia el modelo
Quita la declaración de Paperclip y pon la de Active Storage con el mismo nombre:
# app/models/article.rb
class Article < ApplicationRecord
has_one_attached :cover
end
La validación de tipo de Paperclip (validates_attachment_content_type) no tiene equivalente directo: sustitúyela por una validación propia como la del ejemplo de arriba.
4. Copia los archivos con una tarea rake
Paperclip guardaba cada archivo, por defecto, en public/system/<tabla>/<adjunto>/<id en grupos de tres cifras>/<estilo>/<nombre>. Para el artículo 1, public/system/articles/covers/000/000/001/original/portada.png. La tarea recorre los registros con archivo, abre el original y lo adjunta con Active Storage:
# lib/tasks/paperclip_a_active_storage.rake
namespace :paperclip do
desc "Copia las portadas de Paperclip a Active Storage"
task migrar_portadas: :environment do
Article.where.not(cover_file_name: nil).find_each do |article|
next if article.cover.attached?
ruta = Rails.root.join(
"public/system/articles/covers",
format("%09d", article.id).scan(/\d{3}/).join("/"),
"original",
article.cover_file_name
)
next warn("Article #{article.id}: no existe #{ruta}") unless File.exist?(ruta)
File.open(ruta) do |io|
article.cover.attach(
io: io,
filename: article.cover_file_name,
content_type: article.cover_content_type
)
end
puts "Article #{article.id}: #{article.cover_file_name} copiada"
end
end
end
bin/rails paperclip:migrar_portadas
Article 1: portada.png copiada
Detalles que importan:
- Se puede repetir.
next if article.cover.attached?salta los registros ya migrados; ejecutada por segunda vez, la tarea no copia nada. - Avisa de lo que falta. Si el archivo de un registro no está en su sitio, la tarea escribe
Article 2: no existe …con la ruta y sigue con el siguiente. - Cierra cada archivo.
File.opencon bloque cierra el archivo al terminar, aunque haya miles de registros. - No borra nada. Los originales siguen en
public/system, así que puedes volver atrás si algo falla. - Usa solo el original. Las miniaturas de Paperclip no se copian: Active Storage genera sus propias variantes.
- Si cambiaste la ruta o usas S3, adapta cómo se abre el archivo. Para archivos en la nube, la guía oficial descarga cada uno desde su URL y lo adjunta igual, con
attach(io:, filename:, content_type:).
Comprueba que el contenido es idéntico al original:
article = Article.first
article.cover.download == File.binread("public/system/articles/covers/000/000/001/original/portada.png")
# => true
5. Actualiza vistas y tests
| Paperclip | Active Storage |
|---|---|
image_tag @article.cover.url(:thumb) |
image_tag @article.cover.variant(resize_to_limit: [800, 600]) |
@article.cover.present? o file? |
@article.cover.attached? |
Fábricas que rellenan cover_file_name |
article.cover.attach(...) o file_fixture_upload |
Si muestras listas de artículos con su portada, carga los adjuntos de una vez con Article.with_attached_cover. Sin eso, Rails hace una consulta a la base de datos por cada artículo (el llamado problema N+1).
6. Borra las columnas y la gema
Cuando todo funciona en producción, quita las columnas de Paperclip con una migración:
class RemovePaperclipColumnsFromArticles < ActiveRecord::Migration[8.1]
def change
remove_column :articles, :cover_file_name, :string
remove_column :articles, :cover_content_type, :string
remove_column :articles, :cover_file_size, :bigint
remove_column :articles, :cover_updated_at, :datetime
end
end
Indicar el tipo de cada columna permite deshacerla con bin/rails db:rollback. Después borra la línea de la gema del Gemfile, ejecuta bundle install y, con todo comprobado, la carpeta public/system. En la prueba, tras estos pasos el artículo conserva su portada:
article = Article.first
article.attributes.keys # => ["id", "title", "created_at", "updated_at"]
article.cover.attached? # => true
article.cover.filename.to_s # => "portada.png"
Paperclip en código heredado: has_attached_file
Si mantienes una aplicación que aún no has migrado, así funciona Paperclip. Este código se ha ejecutado con kt-paperclip 8.0.1 sobre Rails 8.1.4.1.
Paperclip necesita ImageMagick para las miniaturas y el comando file para detectar el tipo de archivo:
sudo apt install imagemagick file # Debian o Ubuntu
brew install imagemagick # macOS
A diferencia de Active Storage, Paperclip guarda los datos del archivo en columnas de tu tabla. La gema trae un generador para crearlas:
bin/rails generate paperclip article cover
class AddAttachmentCoverToArticles < ActiveRecord::Migration[8.1]
def self.up
change_table :articles do |t|
t.attachment :cover
end
end
def self.down
remove_attachment :articles, :cover
end
end
t.attachment :cover crea las cuatro columnas cover_file_name, cover_content_type, cover_file_size y cover_updated_at. En el modelo, has_attached_file declara el adjunto y sus tamaños:
class Article < ApplicationRecord
# Un adjunto llamado cover con una miniatura de como mucho 800 × 600
has_attached_file :cover, styles: { thumb: "800x600>" }
# Solo se aceptan imágenes
validates_attachment_content_type :cover, content_type: /\Aimage\/.*\z/
end
Al guardar un artículo con portada, Paperclip rellena las columnas y escribe el original y la miniatura en public/system. Con un archivo de texto, la validación lo rechaza:
article = Article.create!(title: "Hola", cover: File.open("portada.png"))
article.attributes.slice("cover_file_name", "cover_content_type", "cover_file_size")
# => {"cover_file_name" => "portada.png", "cover_content_type" => "image/png", "cover_file_size" => 557}
article.cover.url(:thumb)
# => "/system/articles/covers/000/000/001/thumb/portada.png?1794183951"
texto = Article.new(title: "Mal", cover: File.open("notas.txt"))
texto.save # => false
texto.errors.full_messages # => ["Cover content type is invalid", "Cover is invalid"]
El formulario y los parámetros permitidos son los mismos que con Active Storage. En la vista se elige el tamaño por su nombre:
<%= image_tag @article.cover.url(:thumb) %>
Paperclip y Active Storage, de un vistazo
Resumen nuestro de lo visto arriba:
| Paperclip | Active Storage | |
|---|---|---|
| Estado | Obsoleta (archivada en 2023); kt-paperclip como fork |
Incluida en Rails |
| Columnas en tu tabla | Cuatro (t.attachment) |
Ninguna: usa sus propias tablas |
| Declaración | has_attached_file :cover |
has_one_attached :cover |
| Tamaños | styles: en el modelo, al subir |
variant(...) en la vista, al pedirla |
| Procesador de imagen | ImageMagick | libvips o ImageMagick |
| Validar tipo | validates_attachment_content_type |
Validación propia |
| Almacenamiento en la nube | Adaptadores de S3 y Fog | Servicios en config/storage.yml |
Errores típicos
- Creer que validar el tipo es una barrera de seguridad. Active Storage deduce el tipo mirando el contenido del archivo. En la prueba, un ejecutable con nombre
foto.pngy tipo declaradoimage/pngse detectó comoapplication/x-elfy se rechazó; en cambio, un archivo de texto declarado comoimage/pngse guardó comoimage/pngy pasó la validación. Conclusión nuestra: la validación ayuda al usuario honesto, pero no sustituye a tratar todo archivo subido como no fiable. - Olvidar permitir el parámetro. Si
coverno está enparams.expect(o enpermit), el archivo no se guarda. - Servidor sin libvips. Las variantes fallan con un
NoMethodErrorpoco claro; el aviso real está en el log al arrancar. Instala libvips o cambia a:mini_magick. - Consultas N+1 en las listas. Usa
with_attached_coveral cargar muchos registros con su adjunto. - Borrar los archivos de Paperclip antes de comprobar la migración. Mantén
public/systemhasta haber verificado en producción que todos los registros tienen su adjunto.
Sigue leyendo
- Para validar más campos del mismo modelo: Active Record Validations.
- Para entender las migraciones de los pasos 2 y 6: migraciones en Ruby on Rails.
- Si también gestionas usuarios en la misma aplicación: la gema Devise.
Fuentes
Consultadas el 9 de noviembre de 2026:
- Repositorio de Paperclip: aviso de obsolescencia, recomendación de Active Storage y de
kt-paperclip; archivado el 13 de julio de 2023. - Guía de migración de Paperclip a Active Storage (en español).
- Repositorio de kt-paperclip y su versión 8.0.1 en RubyGems.
- Guía oficial de Active Storage (Rails 8.1.4.1).
El código se ha ejecutado en noviembre de 2026, salvo los comandos de instalación (apt, brew y bundle install), con Ruby 4.0.9 (imagen oficial ruby:latest de Docker), Rails 8.1.4.1, image_processing 1.14.0, ImageMagick 7.1.1 y kt-paperclip 8.0.1. Las salidas son las reales; los números de migración y los tiempos cambiarán en tu equipo.