Last updated 3 May 2013
Installing Rails 4.0 or Rails 3.2.13 on Mac OS X, Ubuntu, or Windows. Up-to-date, detailed instructions on how to install Rails newest releases.
This article from the RailsApps project will show you how to install Rails. It shows how to install the most recent stable release (3.2.13) and the newest version of Rails (4.0.0.rc1). Install both so you can develop projects with the most recent stable version while you explore the features of Rails 4.0.
The article doesn’t offer shortcuts for beginners. It is an in-depth installation guide that professional developers use to configure their working environment for real-world Rails development. For a short guide that covers only Rails 3.2, see the RailsBridge Installfest document.
Follow @rails_apps on Twitter for updates and timely Rails tips.
The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation” so you can stay up to date. Each is accompanied by a tutorial so there is no mystery code. Maintenance and development of the RailsApps applications is supported when you purchase a subscription to the RailsApps Tutorials.
If you have not been closely following the evolution of the Rails platform, here’s a summary of recent developments. To stay informed of new releases, subscribe to Peter Cooper’s Ruby Weekly newsletter and follow @ruby_news or @rails_apps on Twitter.
The article Updating Rails offers instructions and advice. It’s best to update each of your Rails applications when a new version of Rails is released. Occasionally a critical security fix is released. If you don’t update regularly, upgrading several versions at once may require considerable effort, making it difficult to resolve security vulnerabilities quickly.
Use the railsdiff.org site to see differences between versions of the Rails default application.
Rails 4.0.0.rc1 was released April 29, 2013. The Rails 4.0: Beta 1 release announcement offers an overview of new features.
Ruby 2.0 is recommended for Rails 4 (Rails runs faster with Ruby 2.0). Ruby 1.9.3 works but Ruby 1.8.7 will not.
You can follow the progress of Rails 4 development on the EdgeRails.info site.
You can learn more about Rails 4:
What You Need to Know: It will be several months before Rails 4 final is out. For projects deploying to production in the next few months, use Rails 3.2.13. Install Rails 4.0.0.rc1 to get familiar with the changes coming with Rails 4.
What You Need to Know: Use the most recent stable release of Rails because it is the most secure version.
Rails 3.2 was released January 20, 2012. Improvements over Rails 3.1 include faster execution in development mode. The speed of resolving routes also improved. There are many tiny (but helpful) improvements throughout the framework. Rails 3.2 deprecates plugins so you must find Ruby gems to replace any plugins used in earlier Rails projects. You can use Ruby 1.8.7 but you should use Ruby 1.9.3 or Ruby 2.0. See the Rails 3.2.0 Announcement and Ruby on Rails 3.2 Release Notes (with upgrade instructions). There’s a Railscast from Ryan Bates titiled Upgrading to Rails 3.2. Michael Hartl’s popular Ruby on Rails Tutorial book covers Rails 3.2 (Ruby on Rails Tutorial Version 3.2). Finally, José Valim highlights his Five Favorite ‘Hidden’ features in Rails 3.2.
What You Need to Know: Upgrading from Rails 3.1 to Rails 3.2 is easy and yields faster performance (especially in development mode). You may run into issues if your application has routing complexities (the routing engine has changed). For an older application, upgrade to Rails 3.1 before upgrading to Rails 3.2.
For Mac OS X or Ubuntu Linux, it is best to install RVM, the Ruby Version Manager, to install Ruby and Rails. For Windows, I recommend using Nitrous.io or an installation program such as RailsInstaller.
There are alternatives to RVM for switching between versions of Ruby (see a list below including chruby and rbenv) but RVM is popular, well-supported, and full-featured.
Nitrous.io provides a cloud-based development environment including a Unix shell with Ruby and RVM, plus a browser-based file manager and text editor. With a broadband connection, you don’t need to install Ruby on your computer; just use Nitrous.io. The service is by invitation only; request an invitation at Nitrous.io. Accounts are free.
What You Need to Know: Use Nitrous.io if you have trouble installing Ruby on your computer.
Mac OS X comes with Ruby 1.8.7 pre-installed. You must install a newer version of Ruby for developing with Rails.
RVM provides almost everything needed to set up the components needed to install Ruby and Rails. You may see advice elsewhere to use an installation program such as RailsInstaller to set up everything. These installation programs are no longer needed as RVM will set up components needed to install Ruby. I don’t recommend RailsInstaller for experienced developers as it installs RVM at the system level (for all users, not in your user directory) and seldom provides the newest versions of Ruby or Rails.
On Mac OS X you will need a C language compiler to install Ruby and gems that require native extensions. Install Apple’s Xcode Command Line Tools to get the correct C language compiler before you install RVM. Moncef Belyamani has written about How to Install Xcode, Homebrew, Git, RVM, Ruby & Rails.
What You Need to Know: First install Apple’s Xcode Command Line Tools. Then use RVM to install Ruby and Rails.
On Ubuntu, package managers are available to install Ruby. The package managers are often not up to date. Use RVM instead.
$ sudo apt-get install nodejs
and set it in your
If you don’t install Node.js, you’ll need to add this to the Gemfile for each Rails application you build:
Developing with Rails on Windows can be painful. Some gems requiring native extensions may be difficult to install. Be aware that most developers use Mac OS X or Ubuntu to develop Rails applications.
You can avoid native Windows hassles by using Nitrous.io. Or see instructions for Installing Rails on Windows from the Railsbridge Workshops. The instructions recommend using RailsInstaller for Windows. RailsInstaller includes a “DevKit” which installs gcc and other Unix build tools. Also see Amit Kazmirsky’s Installing Rails with MySQL on Windows 8 for important tips. On Windows, use Pik for services similar to RVM.
Another option on Windows is to install Ruby under Cygwin. This gives you a Linux environment on Windows. Make sure you have the following Cygwin packages installed: git, readline, wget, patch, make, gcc, libsqlite3-devel, libxml2-devel, libxslt-devel.
What You Need to Know: Use Nitrous.io or switch to Mac OS X, Ubuntu Linux, or Cygwin if you can. You’ll avoid many headaches.
Use RVM, the Ruby Version Manager, to install Ruby and manage your Rails versions. RVM will install Ruby 2.0 and make it easy to switch between Rails 3.2 and Rails 4.0. You’ll use RVM to create a project-specific gemset for each application you build.
Ruby may already be installed on your computer. You should install the newest version of Ruby. If you have an older version of Ruby installed you don’t need to remove it. RVM will leave your system version of Ruby untouched and use your shell to intercept any calls to Ruby. Any older Ruby and Rails versions will remain on your system and the RVM version will take precedence.
On Mac OS X, you’ll need to install Apple’s Xcode Command Line Tools before installing RVM.
The RVM website explains how to install RVM. RVM includes an “autolibs” option to identify and install components needed for your operating system. See the article RVM Autolibs: Automatic Dependency Handling and Ruby 2.0 for more information.
$ \curl -L https://get.rvm.io | bash -s stable --autolibs=enable --ruby
Note the backslash before “curl” (this avoids potential version conflicts).
The “—ruby” flag will install the newest version of Ruby. Ruby 2.0 patch level 0 was current when this was written. You can check for the current recommended version of Ruby.
If you already have RVM installed, update it to the latest version and install Ruby:
$ rvm get stable --autolibs=enable $ rvm install ruby-2.0.0 $ rvm --default use ruby-2.0.0
To start using RVM, you can either close and reopen your terminal windows or run:
$ source ~/.rvm/scripts/rvm
If you get OpenSSL errors, make sure you are using RubyGems 2.0.3 or newer:
$ gem -v
gem update --system to upgrade the RubyGems system gem if necessary.
For more help, see the article OpenSSL Errors and Rails.
If you get OpenSSL errors after RVM is installed, you may need to remove and reinstall RVM. Use
rvm implode to remove RVM. Check that RVM has been removed with
rvm -v. If it’s still there, it may be installed at the system level for multiple users. This happens if you’ve previously used RailsInstaller (you’ll need to remove RailsInstaller with
If RVM installs successfully but installation of Ruby fails, try:
$ rvm requirements
If Ruby installation succeeds but Ruby 2.0 is not the default when you open a new terminal window, try updating the RVM loading code:
$ rvm get stable --auto-dotfiles
It is also helpful to check RVM notes:
$ rvm notes
For more information about RVM’s automatic detection and installation of system components, see:
$ rvm help autolibs
You can get help directly from the RVM team using the IRC (Internet Relay Chat) channel #rvm on irc.freenode.net:
If you’ve never used IRC, it’s worthwhile to figure out how to use IRC because the RVM team is helpful and friendly. IRC on freenode requires registration (see how to register).
If you have problems installing RVM, use Nitrous.io or try one of the installation programs that provide pre-assembled packages:
Before using RailsInstaller, be sure to remove RVM with
rvm implode (or else the single-user version of RVM will hide the multi-user version of RVM installed by RailsInstaller).
If you want to use RailsInstaller on Mac OS X, you should use the newer version available (it contains Ruby 2.0):
If you are a student or hobbyist and you do not intend to release a Rails project to production, you can use older versions of Ruby or Rails provided by RailsInstaller. If you have plans to release a Rails project to production (that is, to deploy it where others can use it), you should use RVM to update to Ruby 2.0 (it is faster) and you must update Rails (versions before 3.2.13 have significant security vulnerabilities).
If you decide to remove RailsInstaller, use
open /Applications/RailsInstallerOSX-Uninstaller.app. It is important to remove RailsInstaller before installing RVM because RailsInstaller installs an older version of RVM at the system level and (by default) a new install of RVM will install at the user level.
Not everyone likes the shell management approach of RVM. If you are an experienced Unix administrator, you may prefer one of the many alternatives to RVM.
Chruby provides a streamlined utility for switching between Ruby versions.
Sam Stephenson offers an alternative to RVM named rbenv. With rbenv, use Jamis Buck’s rbenv-gemset to switch between gemsets. The utilities rbenv and rbenv-gemset are less “magic” than RVM and can be useful if you encounter issues with RVM. If you want to try rbenv, see notes for installing Ruby on MacOS X 10.7.3 with XCode 4.3 and rbenv.
There are many more alternatives to RVM on this list.
MRI, Matz’s Ruby Interpreter, is the reference implementation. It is the default when you install Ruby 2.0 using RVM. There are other Ruby interpreters available for specialized use:
rvm list known for a full list. Any can be installed using RVM.
Installing Ruby with RVM creates a default “global” gemset.
To see a list of the gemsets you have installed:
$ rvm gemset list
With a new installation of Ruby (using RVM), you’ll see just one gemset.
See what gems are installed in the “global” gemset:
$ rvm gemset use global $ gem list
Several gems are installed with Ruby:
RVM installs two additional gems:
A trouble-free development environment requires the newest versions of these gems. If you’ve just installed Ruby, you’ll have newest gems. If you are using a previous installation of Ruby, these gems may need updating. Check before installing Rails.
You should have:
Check the RubyGems system gem version:
$ gem -v
Be sure you have installed RubyGems 2.0.3 or newer. With older versions, you may have trouble with OpenSSL and Ruby 2.0.
gem update --system to upgrade the RubyGems system gem.
Check for current versions of other gems:
$ gem list
gem update rake to upgrade Rake.
gem update bundler to upgrade Bundler.
gem update rubygems-bundler to upgrade Rubygems-Bundler.
You can track updates to gems by creating an account at RubyGems.org and visiting your dashboard. Search for each gem you use and “subscribe” to see a feed of updates in the dashboard (an RSS feed is available from the dashboard). As an alternative, use the Gemnasium or VersionEye services which survey your GitHub repo and send email notifications when gem versions change. The services are for public repositories with a premium plan for private repositories.
Check for the current version of Rails.
If you want, you can install Rails directly into the global gemset. However, many developers prefer to keep the global gemset sparse and install Rails into project-specific gemsets. It’s advisable to create a new gemset for each application you build.
Before we do that, let’s consider the options you have for installing Rails.
If you want the most recent stable release:
$ gem install rails $ rails -v
If you want the newest beta version or release candidate, you can install with
$ gem install rails --pre $ rails -v
Or you can get a specific version (just in case the newest version is broken).
For example, if you want the Rails 4.0.0.rc1 release:
$ gem install rails --version=4.0.0.rc1 $ rails -v
If you have existing Rails applications running under Ruby 1.9.3, you’ll need an RVM Ruby and gemset for Ruby 1.9.3 and Rails 3.2.13, the most recent stable release of Rails. Ruby 1.9.3 patch level 392 was the most recent secure release before Ruby 2.0.
$ rvm install ruby-1.9.3-p392 $ rvm use ruby-1.9.3-p392@Rails3.2.13 --create $ rvm gemset list
When you want to work with an existing Rails application, switch to the ruby-1.9.3-p392@Rails3.2.13 gemset:
$ rvm use ruby-1.9.3-p392@Rails3.2.13
You should begin testing any existing Rails applications with Ruby 2.0. You should create a new gemset for Ruby 2.0 and Rails 3.2.13, the most recent release of Rails patched to work with Ruby 2.0. Here’s how, assuming you’ve already installed Ruby 2.0:
$ rvm use ruby-2.0.0 $ rvm use ruby-2.0.0@Rails3.2.13 --create $ rvm gemset list $ gem install rails --version=3.2.13 $ gem list
When you want to test an existing Rails application with Ruby 2.0, switch to the ruby-2.0.0@Rails3.2.13 gemset:
$ rvm use ruby-2.0.0@Rails3.2.13
Change the application’s Gemfile to specify
gem 'rails', '3.2.13' and run
bundle update to test the application with Ruby 2.0 and Rails 3.2.13.
To begin migrating existing projects to Rails 4.0, you can create another gemset:
$ rvm use ruby-2.0.0 $ rvm use ruby-2.0.0@Rails4.0.0 --create $ rvm gemset list $ gem install rails --pre $ gem list
For advice about migrating an application from Rails 3.2 to Rails 4.0, see Andy Lindeman’s ebook Upgrading to Rails 4.
Next we’ll look at creating new Rails 3.2 and Rails 4.0 projects using Ruby 2.0.
Here’s how to create a project-specific gemset and install Rails 3.2.13, the most recent release of Rails patched to work with Ruby 2.0.
Instead of installing Rails into the global gemset and running
rails new, we’ll create a root directory for a new application, create a new gemset, install Rails, and then generate a starter application.
$ mkdir myRails32app $ cd myRails32app $ rvm use ruby-2.0.0@myRails32app --ruby-version --create $ gem install rails --version=3.2.13 $ rails new .
We’ll name the new application “myRails32app.” Obviously, you can give it any name you like.
With this workflow, you’ll first create a root directory for your application. Then with one command you can create a new project-specific gemset. With the new gemset in place, you’ll next install Rails and create a new Rails application. Notice that you use the Unix “dot convention” to specify that you want to build the application in the current directory.
The option “—ruby-version” creates .ruby-version and .ruby-gemset files in the root directory. RVM recognizes these files in an application’s root directory and loads the required version of Ruby and the correct gemset whenever you enter the directory.
When we create the gemset, it will be empty (though it inherits use of all the gems in the global gemset). We immediately install Rails. The command
gem install rails --version=3.2.13 installs the most recent release of Rails patched to work with Ruby 2.0, which was version 3.2.13 at the time this was written.
Finally we run
rails new .. We use the Unix “dot” convention to refer to the current directory. This assigns the name of the directory to the new application.
This approach is different from the way most beginners are taught to create a Rails application. Most instructions suggest using
rails new myRails32app to generate a new application and then enter the directory to begin work. Our approach makes it easy to create a project-specific gemset and install Rails before the application is created.
rails new command generates the default Rails starter app. If you wish, you can use the Rails Composer tool to generate a starter application with a choice of basic features and popular gems.
Here’s how to generate a new Rails application using the Rails Composer tool:
$ mkdir myRails32app $ cd myRails32app $ rvm use ruby-2.0.0@myRails32app --ruby-version --create $ gem install rails --version=3.2.13 $ rails new . -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
See below for a list of starter applications from the RailsApps project.
For a “smoke test” to see if everything runs, display a list of Rake tasks.
$ rake -T
There’s no need to run
bundle exec rake instead of
rake when you are using RVM (see RVM and bundler integration).
Now let’s create a project-specific gemset and install the pre-release version of Rails 4.0.
This can be a Rails application that you use to become familiar with the features of Rails 4.0.
$ mkdir myRails4app $ cd myRails4app $ rvm use ruby-2.0.0@myRails4app --ruby-version --create $ gem install rails --pre $ rails new .
We’ll name the new application “myRails4app.” Obviously, you can give it any name you like.
As of this writing, there are no Rails 4.0 starter applications from the RailsApps project.
This concludes the instructions for installing Ruby and Rails. Read on for additional advice and tips.
Rails uses the SQLite database by default. Mac OS X come with SQLite pre-installed and there’s nothing to configure. On Windows, if you use a pre-assembled package to install Rails, it will likely have SQLite pre-installed.
On Ubuntu Linux, install SQLite with:
$ sudo apt-get install sqlite3 libsqlite3-dev
Though SQLite is adequate for development (and even some production applications), a new Rails application can be configured for other databases. The command
rails new myapp --database= will show you a list of supported databases.
Supported for preconfiguration are: mysql, oracle, postgresql, sqlite3, frontbase, ibm_db, sqlserver, jdbcmysql, jdbcsqlite3, jdbcpostgresql, jdbc.
For example, to create a new Rails application to use PostgreSQL:
$ rails new myapp --database=postgresql
--database=postgresql parameter will add the pg database adapter gem to the Gemfile and create a suitable config/database.yml file. Here’s an article that explains how to install PostgreSQL on Mac OS X:
The starter application you created with
rails new is very basic.
Use the Rails Composer tool to build a full-featured Rails starter app.
You’ll get a choice of starter applications with basic features and popular gems.
Create a starter app using the Rails Composer application template.
From within an empty application root directory:
$ rails new . -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
Or, using the more conventional approach:
$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
You can add the
-T flags to skip Test::Unit if you are using RSpec for testing.
You can add the
-O flags to skip Active Record if you are using a NoSQL datastore such as MongoDB.
The RailsApps project provides example apps that show how real-world Rails applications are built. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Dozens of developers use the apps, report problems as they arise, and propose solutions as GitHub issues. There is a tutorial for each one so there is no mystery code.
|Twitter Bootstrap, Devise, CanCan||Tutorial||Devise for authentication, CanCan for authorization, Twitter Bootstrap for CSS|
|Rails Membership Site with Stripe||Tutorial||Site with subscription billing using Stripe|
|Rails Membership Site with Recurly||Tutorial||Site with subscription billing using Recurly|
|Startup Prelaunch Signup App||Tutorial||For a startup prelaunch signup site|
|Devise, RSpec, Cucumber||Tutorial||Devise for authentication with ActiveRecord and SQLite for a database|
|Devise, Mongoid||Tutorial||Devise for authentication with a MongoDB datastore|
|OmniAuth, Mongoid||Tutorial||OmniAuth for authentication with a MongoDB datastore|
|Subdomains, Devise, Mongoid||Tutorial||Basecamp-style subdomains with Devise and MongoDB|
You should set up your application with a source control repository using git. If you are developing with Rails, git is an essential tool. Use git to roll back code changes as needed, when you are collaborating with others, and when you must deploy an app for hosting with a service such as Heroku. See the article:
If git is installed on your computer and you’ve used a RailsApps application template to create your starter app, you’ll already have a git repository.
If you’ve already created an application with the command
rails new myapp, you can still create a project-specific gemset. Here’s how to create a gemset for an application named “myapp” and create .ruby-version and .ruby-gemset files in the application’s root directory:
$ rvm use ruby-2.0.0@myapp --ruby-version --create
You’ll need to install Rails and the gems listed in your Gemfile into the new gemset by running:
$ gem install rails $ bundle install
If you have already created both an application and a gemset, but not .ruby-version and .ruby-gemset files, here’s how to add the files. For example, if you want to use an existing gemset named “ruby-2.0.0@myapp”:
$ echo "ruby-2.0.0" > .ruby-version $ echo "myapp" > .ruby-gemset
Using .ruby-version and .ruby-gemset files means you’ll automatically be using the correct Rails and gem version when you switch to your application root directory on your local machine.
If you wish to run your own servers, you can deploy a Rails application using Capistrano deployment scripts. However, unless system administration is a personal passion, it is much easier to deploy your application with a “platform as a service” provider such as Heroku.
For easy deployment, use a “platform as a service” provider such as:
For deployment on Heroku, see the article:
By design, Rails encourages practices that avoid common web application vulnerabilities. The Rails security team actively investigates and patches vulnerabilities. If you use the most current version of Rails, you will be protected from known vulnerabilities. See the Ruby On Rails Security Guide for an overview of potential issues and watch the Ruby on Rails Security Mailing List for announcements and discussion.
rails new command, a unique secret key is generated and written to the config/initializers/secret_token.rb file. If you’ve generated a Rails application and committed it only to a private GitHub repository, you do not need to change the secret key. However, if you’ve cloned a public GitHub repository or made your application publicly available on GitHub, you must change the secret key when you deploy. The command
rake secret generates a new random secret you can use. The command won’t install the key; you have to copy the key from the console output to the config/initializers/secret_token.rb file. Remember, you should never deploy an application to production that uses a publicly available secret token (obviously, it is not secret if it is public!).
If you get a “segfault” when you try
rails new, try removing and reinstalling RVM. If you are not using the current version of Mac OS X, you should upgrade before installing RVM.
Ruby and RubyGems (starting with Ruby 1.9.3p194 and RubyGems 1.8.23) require verification of server SSL certificates when Ruby makes an Internet connection via https. If you run
rails new and get an error “Gem::RemoteFetcher::FetchError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate” see this article suggesting solutions: OpenSSL errors and Rails.
Are you getting an error “OpenSSL certificate verify failed” when you try to generate a new Rails app from an application template? See this article suggesting solutions: OpenSSL errors and Rails.
Your best source for help with problems is Stack Overflow. Your issue may have been encountered and addressed by others.
You can also try Rails Hotline, a free telephone hotline for Rails help staffed by volunteers.