Skip to main content

Image processing

Architecture overview

In a typical Solidus store, you can upload images for products and taxons.

Under the hood, Solidus will use a different file processing library depending on the Rails version: Active Storage is the default starting from Rails 6.1, while Paperclip is used in earlier versions.


Active Storage cannot be used in Rails 6.0 or earlier because it doesn't support public URLs, which Solidus needs to serve images to your users. If you're on Rails 6.0 or earlier, you have to use Paperclip.

While Paperclip is deprecated and will be removed in the near future, Solidus provides a compatibility layer that abstracts the differences between the two libraries, in order to offer an easier migration path to existing Paperclip users.

Customizing image sizes

By default, Solidus uses the following sizes for images:

  • mini: 48x48
  • small: 400x400
  • product: 680x680
  • large: 1200x1200

You can access the URL for a specific sizes by calling, e.g. Spree::Image#url:

image = Spree::Image.first

If you're building a custom storefront, you may also want to change the sizes of the images in your store. You can do this by applying an override to Spree::Image:

module AmazingStore
module Spree
module Image
module CustomizeSizes
def self.prepended(klass)
klass.attachment_definitions[:attachment][:styles] = {
mini: '48x48>',
small: '400x400>',
product: '680x680>',
large: '1200x1200>',
jumbo: '1600x1600>'

::Spree::Image.prepend self

Now that you changed your sizes, try getting the URL for your new jumbo size or large sizes:

image = Spree::Image.first
taxon = Spree::Taxon.first

Solidus will generate the new sizes and return their URLs!

You can also use your new styles in the image partial:

< %= render 'spree/admin/shared/image', image:, size: :jumbo %>

Customizing the allowed MIME types

By default, Solidus only accepts PNG, JPEG and GIF images. If you want to accept additional MIME types, e.g. WebP, you can do it via the allowed_image_mime_types configuration option:

Spree.config do |config|
# ...

config.allowed_image_mime_types = %w(image/jpeg image/jpg image/png image/gif image/webp).freeze

Replacing an attachment module

If the change you want to apply cannot be made through the existing configuration options, you can entirely replace the product image or taxon icon attachment module with your own.

This can be useful, for example, if you need to customize your image styles or perform custom post-processing operations on your image such as watermarking, compression, etc.


When replacing an attachment module, we recommend copy-pasting the original module first and only changing what you need. The right starting point will depend on whether you're using ActiveStorage or Paperclip. You can find the modules for Spree::Image here and the modules for Spree::Taxon here.

Here's an example for the product image attachment:

module AmazingStore
module ImageAttachment
# ...

Once you have your custom attachment module, you need to tell Solidus to use it:

Spree.config do |config|
# ...
config.image_attachment_module = 'AmazingStore::ImageAttachment'

To replace the taxon attachment, follow the same process, but set the taxon_attachment_module configuration option instead.