Skip to main content

Bundler cheat sheet


Cheat sheet with basic commands for Bundler, a package manager that provides a consistent environment for Ruby projects by tracking and installing the exact gems (software packages) and versions that are needed.

Introduction #

These commands should help you get started with Bundler and manage your Ruby project dependencies effectively. Adjust the commands and Gemfile according to your project’s needs.

Installing #

Installing Bundler #

gem install bundler

Installing specific groups of gems #

bundle install --without production

Installing gems from a specific source #

# Gemfile
source ''

gem 'gem_name', 'version'

Using local or custom gems #

# Gemfile
gem 'gem_name', path: '/path/to/local/gem'

Install gems faster #

Define the maximum number of parallel download and install jobs with --jobs=[<number>] or -j[<number>]. The default is 1.

bundle install -j3

Installing dependencies #

bundle install

Install gems to a local vendor directory #

--path specifies a different path than the system default $BUNDLE_PATH or $GEM_HOME. Bundler will remember this value for future installs on the machine.

Installs dependencies, even gems that are already installed to your system gems, to a location other than your system’s gem repository. Common places are vendor/bundle or .bundle. In the following example, I use vendor/bundle:

bundle install --path vendor/bundle

It is recommended to first run this command, before installing gems.

Gemfile #

Creating a Gemfile #

Create a file named Gemfile in your project directory and specify your dependencies.

# Gemfile
source ''

gem 'gem_name', 'version'

Creating a lock file (Gemfile.lock) #

bundle lock

Specifying a Ruby version #

# Gemfile
ruby '2.7.4'

Specifying a platform-specific gem #

# Gemfile
platform :ruby do
  gem 'gem_name'

platforms :jruby do
  gem 'jruby_specific_gem'

Maintenance #

Checking for outdated gems #

The command lists all the gems in the project that have newer versions available than what is currently specified in the Gemfile.lock.

bundle outdated

Updating dependencies #

Updates all the gems listed in the Gemfile to the latest versions that match the version constraints specified. If no version constraints are given, it updates to the latest version available. update re-resolves all gem dependencies, which can lead to other gems being updated as well if their dependencies have changed. It modifies Gemfile.lock to reflect the new versions of the gems.

bundle update

Cleaning up unused gems #

Removes all the gems that are not listed in Gemfile or Gemfile.lock. These are typically gems that were installed previously but are no longer needed based on the current Gemfile.

bundle clean [--dry-run] [--force]

Checking for security vulnerabilities #

bundle audit

Viewing a list of installed gems and their versions #

bundle list

Viewing detailed information about a gem #

bundle show gem_name

Initializing a new project #

bundle init

Scripts #

Running a script in the context of the bundle #

bundle exec ruby script.rb

Running scripts with a clean environment #

bundle exec --keep-file-descriptors ruby script.rb

Further readings #

Sources and recommended, further resources on the topic:


Jonas Jared Jacek • J15k

Jonas Jared Jacek (J15k)

Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See:


License: Bundler cheat sheet by Jonas Jared Jacek is licensed under CC BY-SA 4.0.

This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:

<p xmlns:cc="" xmlns:dct=""><a property="dct:title" rel="cc:attributionURL" href="">Bundler cheat sheet</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="">Jonas Jared Jacek</a> is licensed under <a href="" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>

For more information see the DITig legal page.

“Form ever follows function.”

Louis Henry Sullivan, American architectThe Tall Office Building Artistically Considered, - IT quotes