Managing Gems with Bundler
Last updated June 28, 2024
Table of Contents
Using Bundler
To install Bundler, run:
Commands are prefixed with > to show you must run them in a command prompt. Don’t copy the > character when you run the command.
> gem install bundler
Create a file named Gemfile in the root of your app specifying what gems are required to run it:
source "https://rubygems.org"
gem 'sinatra', '4.0'
Add this file to the git repository since it’s part of the app. Also add the .bundle directory to your .gitignore file. After adding the Gemfile, it makes it easy for other developers to get their environment ready to run the app:
> bundle install
This command ensures that all gems specified in the Gemfile are available for your application. Running bundle install also generates a Gemfile.lock, which you must add to your git repository. The Gemfile.lock ensures that deployed versions of gems on Heroku match the version installed locally on your development machine.
If your Gemfile.lock specifies a bundler version prior to 2.2 and the PLATFORMS section of your Gemfile.lock contains Windows entries, such as mswin or mingw, then Heroku will ignore the Gemfile.lock file. We recommend upgrading to Bundler 2.2 or later.
Windows Support with Bundler 2.2 and Later
Heroku supports deploying applications developed on Windows, but production dynos will run on a different operating system). To ensure that your Heroku production application installs the same versions of gems you’re using locally for development on your Windows machine, we recommend updating your application to Bundler 2.2 or later. You can upgrade your bundler version by running the commands:
> gem install bundler
> bundle update --bundler
> bundle lock --add-platform ruby
> bundle lock --add-platform x86_64-linux
> bundle install
> git add Gemfile.lock
> git commit -m "Upgrade bundler"
After running these commands, Windows applications using bundler 2.2+ will rely on bundler’s support for multiple platforms to find and install an appropriate version.
Windows Support with Bundler Before 2.2
If your application can’t upgrade to bundler 2.2 or later, then when you deploy, the Gemfile.lock file will be deleted and regenerated. You can find more information about this behavior on the Ruby buildpack’s GitHub repository.