Upgrading to the Heroku Toolbelt

Heroku Toolbelt

The original version of the Heroku command-line tool was available as a Ruby gem. This made it easy to install on all platforms with just one command: gem install heroku. While we love this simplicity, it depends on a system install of Rubygems. To get this experience on widely varying development environments, we created the Heroku Toolbelt, a one-click installer for every major platform.

Going forward we will be sunsetting support for the heroku gem in favor of the Toolbelt. If you're already using the Toolbelt, you're fine to stop reading now. To verify whether you're using the gem or Toolbelt, use heroku version:

$ heroku version
heroku-toolbelt/2.32.11 (universal-darwin12.0) ruby/1.9.3 autoupdate

If the output includes heroku-toolbelt, you're all set.

Advantages of the Toolbelt

The Toolbelt is a self-contained installer that gives you everything you need to use Heroku. Some advantages of the Toolbelt include:

  • The Toolbelt is much faster, shaving several seconds off the startup of each heroku command.

  • The Toolbelt packages its own dependencies and will not conflict with your existing development tools.

  • The Toolbelt automatically keeps itself up to date with the latest available bug fixes, security updates, and new features.

Sunsetting the Gem

Starting today, all users still using the gem will see reminders to upgrade to the Toolbelt. This reminder will appear at most once daily when running a heroku command.

On December 1, 2012, we will stop releasing new updates to the heroku gem.

If you are using the heroku gem in your app to programatically access the Heroku API, we encourage you to migrate your code to the heroku-api gem. Existing versions of the heroku gem will remain on rubygems.org so any code referencing these gems should continue to function as long as the API they reference is available.

We encourage all users to upgrade to the Toolbelt today to take advantage of this new, streamlined CLI experience.

Browse the blog archives or subscribe to the full-text feed.