Ruby Bundler — Dependency Management with Gemfile and Bundler Commands

In this tutorial, you will learn about Ruby Bundler. We cover key concepts, practical examples, and best practices to help you master this topic.

Bundler manages Ruby gem dependencies through Gemfile specification with install, exec, and update commands for reproducible application environments.

What You'll Learn

• Gemfile structure and syntax
• Bundler commands: install, exec, update, outdated
• Gem groups and environments
• Gemfile.lock and version resolution

Why It Matters

Bundler ensures consistent dependencies across development, test, and production. Every Rails project uses Bundler. DodaZIP uses Bundler for reproducible builds.

Real-World Use

Project dependency management, CI/CD pipeline consistency, team collaboration, deployment reproducibility.

flowchart LR
    A["Bundler"] --> B["Gemfile"]
    B --> C["Gemfile.lock"]
    C --> D["bundle install"]
    D --> E["bundle exec"]
    A:::current --> B
    style A fill:#2563eb,stroke:#2563eb,color:#fff
    style B fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style C fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style D fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style E fill:#f1f5f9,stroke:#94a3b8,color:#64748b

Gemfile

source "https://rubygems.org"

ruby "3.3.0"

gem "rails", "~> 7.1"
gem "pg"
gem "puma"

group :development do
  gem "pry"
  gem "rubocop"
end

group :test do
  gem "rspec"
  gem "factory_bot"
end

group :development, :test do
  gem "debug"
end

Gem Version Syntax

gem "foo", "1.2.3"        # Exact version
gem "foo", "~> 1.2"       # Pessimistic: >= 1.2 and < 2.0
gem "foo", "~> 1.2.3"     # Pessimistic: >= 1.2.3 and < 1.3
gem "foo", ">= 1.0"        # Minimum version
gem "foo", ">= 1.0", "< 2.0"  # Range
gem "foo", github: "user/repo"  # From GitHub
gem "foo", path: "../foo"  # Local path

Bundle Install

bundle install
# Fetching gem metadata from https://rubygems.org/...
# Resolving dependencies...
# Using rake 13.0.6
# Using json 2.6.3
# Bundle complete! 12 Gemfile dependencies, 45 gems now installed.
# Use `bundle info [gemname]` to see where a bundled gem is installed.

Bundle Exec

bundle exec rails server
bundle exec rspec
bundle exec rubocop

Bundle Update

bundle update
# Update all gems to latest versions within Gemfile constraints

bundle update rails
# Update only rails and its dependencies

Bundle Outdated

bundle outdated
# Outdated gems included in the bundle:
#   * rails (newest 7.1.2, installed 7.0.8)
#   * nokogiri (newest 1.16.0, installed 1.15.4)

Gem Groups

# Gemfile
gem "rspec", group: :test  # Only in test environment

# Usage
bundle install                # All groups
bundle install --without production  # Exclude production

Gemfile.lock

GEM
  remote: https://rubygems.org/
  specs:
    actioncable (7.1.2)
      actionpack (= 7.1.2)
    actionmailer (7.1.2)
      actionpack (= 7.1.2)
    actionpack (7.1.2)
      activesupport (= 7.1.2)

PLATFORMS
  x86_64-linux

DEPENDENCIES
  rails (~> 7.1)

BUNDLED WITH
   2.5.3

Custom Gem Source

source "https://my-private-gem-server.com" do
  gem "my-private-gem"
end

Common Mistakes

1. Not checking in Gemfile.lock

# Always commit Gemfile.lock to version control for reproducible builds.
# .gitignore should NOT include Gemfile.lock for apps.

2. Forgetting bundle exec

# Bad: rspec (might use wrong version)
# Good: bundle exec rspec (uses Gemfile.lock versions)

3. Using wrong Ruby version

# gem install rails  # Installs for system Ruby
# bundle exec rails  # Uses project Ruby version

4. Platform-specific gems

gem "nokogiri"  # Works everywhere
# Avoid platform-specific gems in shared Gemfile

5. Not using groups

# Put development-only gems in :development group
# They won't install in production

Practice Questions

1. What does Gemfile.lock do? Locks exact gem versions after resolution. Ensures every environment uses the same versions.

2. When do you run bundle update? When you want to upgrade gem versions within Gemfile constraints. Use bundle outdated first.

3. What is bundle exec? Runs a command using the gem versions specified in Gemfile.lock, not system gems.

4. How do gem groups work? Gems in :development group only install in development. Use bundle install --without test to exclude groups.

Challenge: Create a Gemfile for a web application with Rails, PostgreSQL, RSpec, RuboCop, and Puma.

source "https://rubygems.org"

ruby "3.3.0"

gem "rails", "~> 7.1"
gem "pg"
gem "puma", "~> 6.0"

group :development, :test do
  gem "debug"
  gem "rspec-rails"
end

group :development do
  gem "rubocop"
  gem "rubocop-rails"
end

group :test do
  gem "factory_bot_rails"
  gem "shoulda-matchers"
end

FAQ

{{< faq question="What is the difference between gem install and bundle install?" >}} gem install installs globally. bundle install installs into the project's bundled environment, respecting Gemfile.lock versions. {{< /faq >}}

{{< faq question="Should I commit Gemfile.lock?" >}} Yes for applications. No for libraries/gems — publish the gemspec instead. Lockfile ensures deployment consistency. {{< /faq >}}

{{< faq question="How do I fix dependency conflicts?" >}} Use bundle update <gem> to selectively update. Check bundle outdated. If conflicts persist, loosen version constraints in Gemfile. {{< /faq >}}

{{< faq question="What is BUNDLED WITH in lockfile?" >}} The Bundler version used to generate the lockfile. Ensures the correct Bundler version is used in deployment. {{< /faq >}}

{{< faq question="Can I use Bundler with system gems?" >}} Yes, but bundle exec ensures isolation. Use bundle clean to remove unused gems. bundle pristine restores gem state. {{< /faq >}}

Try It Yourself

mkdir my_app && cd my_app

cat > Gemfile << 'EOF'
source "https://rubygems.org"

gem "sinatra"
gem "puma"
gem "json"
EOF

bundle install
bundle exec ruby -e "require 'sinatra'; puts Sinatra::VERSION"

Expected output:

Fetching gem metadata from https://rubygems.org/...
Bundle complete! 3 Gemfile dependencies, 5 gems now installed.
2.0.0

What's Next

Now that you understand gems and Bundler, explore Ruby projects and the ecosystem.