Nivel inicial13 min de lectura · Publicado el

Paperclip gem en Ruby on Rails y Active Storage

Subir archivos en Rails: la ficha de Article guarda solo la referencia cover y la foto se guarda aparte, con has_one_attached :cover Adjuntos: la foto va aparterubentejera.com Articletitlecoverla foto, apartehas_one_attached :cover
La ficha es la fila de Article: solo lleva grapada la referencia, cover. La foto se guarda aparte, en una carpeta o en la nube. Hoy se hace con Active Storage y has_one_attached :cover; Paperclip está obsoleta.

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) y active_storage_variant_records (las miniaturas generadas).
  • El archivo va a un servicio. En config/storage.yml eliges 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_attached para un archivo y has_many_attached para 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:

  1. La gema image_processing, que las aplicaciones nuevas de Rails 8.1 ya traen en el Gemfile.
  2. 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.

  1. Haz una copia de seguridad de la base de datos y de los archivos.
  2. Instala Active Storage.
  3. Cambia el modelo a has_one_attached.
  4. Copia los archivos con una tarea rake.
  5. Actualiza vistas y tests.
  6. 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.open con 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.png y tipo declarado image/png se detectó como application/x-elf y se rechazó; en cambio, un archivo de texto declarado como image/png se guardó como image/png y 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 cover no está en params.expect (o en permit), el archivo no se guarda.
  • Servidor sin libvips. Las variantes fallan con un NoMethodError poco 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_cover al cargar muchos registros con su adjunto.
  • Borrar los archivos de Paperclip antes de comprobar la migración. Mantén public/system hasta haber verificado en producción que todos los registros tienen su adjunto.

Sigue leyendo

Fuentes

Consultadas el 9 de noviembre de 2026:

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.