System requirements

The following software is required to get Solidus running:

We recommend using Homebrew to install these dependencies on your Mac. Throughout this article, we will use the brew command for installing system dependencies. The Ruby documentation also recommends using Homebrew if you need to upgrade from your system's Ruby.

We also recommend configuring your development environment so that you can install RubyGems without sudo .

Quick start

Using Homebrew, you can install all of the requirements using the following commands:

      brew install ruby sqlite3 imagemagick
gem install rails


See more detailed installation information below.

Upgrade Ruby on macOS

If you run macOS Sierra or an older OS, you system's version of Ruby will need to be upgraded from 2.0.x to 2.2.2 or newer. You can check what version of Ruby you have installed with the following command:

      ruby --version


The Ruby documentation recommends installing another, newer instance of Ruby using Homebrew:

      brew install ruby


Homebrew prioritizes the Homebrew installation of Ruby (/usr/local/bin/ruby) above the system installation (/usr/bin/ruby).

Install SQLite 3

Rails and Solidus use SQLite 3 as the default relational database. SQLite is a widely-supported, lightweight way to send and receive data. Using Homebrew, you can install the latest version of SQLite 3 using the following command:

      brew install sqlite3


Alternatively, you can download the pre-compiled binary from the SQLite website .

After installation, check the version number:

      sqlite3 --version


If all is well, this command will return a version number that looks something like 3.16.0 2016-11-04 19:09:39 0f3eed3324eda2a2b8d3301e5a43dc58a3a5fd5f.

Install Rails

Rails includes everything you need to build and extend a web application. Once you have Ruby and SQLite 3 installed on your system, you can install Rails via the RubyGems gem command that comes as a part of Ruby:

      gem install rails


This will install Rails as well as its dependencies.

Install Libvips

If you are upgrading from an older version of Solidus (where Paperclip was used for product images), and are continuing to use Paperclip for your product images (see the section on [product images][product-images] for more details), you will need to install ImageMagick.

If you set up your store with Solidus v3 or newer, you are using ActiveStorage for your product images by default. As outlined in the the ActiveStorage guide you have the choice to install libvips (v8.6 or newer) as an alternative to ImageMagick. Libvips can be both faster and less memory intensive than ImageMagick.

To install libvips via homebrew, use the command:

      brew install libvips



Install ImageMagick

ImageMagick helps you create, edit, and save to hundreds of image file formats. It is required by Paperclip , which Solidus currently uses to handle file attachments. To install ImageMagick via Homebrew, use the command:

      brew install imagemagick


Alternatively, you can download a pre-compiled binary for macOS from the ImageMagick website .


Solidus is an open source platform supported by the community. We encourage everyone using Solidus to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.