How to Use Byebug to Debug Ruby Code: A Step-by-Step Guide

Debugging is a critical skill for every Développeur Ruby, allowing you to inspect runtime behavior, track down elusive bugs, and understand complex code flows. Among the many tools available, Byebug stands out as a reliable, feature-rich command-line debugger.

As of January 2026, Byebug’s latest version is 12.0.0 (released March 25, 2025). While Ruby 3.1+ includes the modern debug gem as the standard (and Rails 7+ defaults to it), Byebug remains widely used in legacy projects, older Applications Rails, and by developers who prefer its straightforward interface.

This guide covers everything you need: what Byebug is, its key features, installation, usage, and best practices.

What is Byebug?

Byebug is an open-source, command-line debugger for Ruby, designed specifically for Ruby 2.0 and later (including Ruby 3.x). It enables you to pause program execution at specific points, step through code line by line, inspect variables and the call stack, and evaluate expressions in real time.

Implemented as a C extension for speed, Byebug leverages Ruby’s TracePoint API for controlling execution (e.g., line hits, method calls) and the Debug Inspector API for navigating the stack. This makes it independent of Ruby’s internal changes, ensuring broad compatibility without relying on core patches.

Byebug replaced older tools like ruby-debug and became the default debugger in Rails 5 and 6. It’s maintained on GitHub and continues to receive updates for compatibility.

Typical Byebug console sessions: the prompt, code context, colored output, and variable inspection in action.

Key Features of Byebug

Byebug offers a rich set of traditional debugging capabilities:

• Stepping through code: Run one line at a time with next (step over), step (step into), and finish (run until method returns).
• Breakpoints: Simple inline (byebug in code) or dynamic setting (by line, method, or condition).
• Variable inspection: Evaluate any expression, pretty-print complex objects, list locals/instances, and auto-display values.
• Call stack navigation: Full backtraces, frame switching, and moving up/down the stack.
• Exception handling: Catch specific exceptions or enable post-mortem debugging on crashes.
• REPL integration: Drop into IRB for interactive experimentation.
• Remote debugging: Connect to running processes.
• Thread support: Handle multi-threaded applications.
• Extensibility: Excellent integration with Pry via pry-byebug for enhanced REPL features.

These make Byebug powerful yet simple—no graphical overhead, just a clean terminal interface.

Examples of Byebug in use: colored formatting, stepping commands, and breakpoint hits.

Byebug Installation

For Bundler projects (e.g., Rails):

ruby
# Gemfile
group :development, :test do
  gem 'byebug'
end

Run:

bash
bundle install

For standalone scripts:

bash
gem install byebug

Starting a Byebug Debugging Session

Inline Breakpoints (Most Common)

Add byebug (or alias debugger) in your code:

ruby
def calculate_total(items)
  total = 0
  items.each do |item|
    byebug  # Execution pauses here
    total += item.price
  end
  total
end

Run normally (ruby script.rb or rails server). It pauses at the breakpoint with the (byebug) prompt.

Command-Line Start

bash
byebug script.rb [args]

Essential Commands

At the (byebug) prompt (help for full list):

• Code viewing: list/l (show context), list – (previous).
• Inspection: Type variable name, p/pp expression, var local/instance, display expr.
• Stack: backtrace/bt, up/down, frame n.
• Execution: continue/c, next/n, step/s, finish.
• Breakpoints: break file:line or break Method, info breakpoints, delete, condition.
• Advanced: irb, catch Exception, edit, set postmortem.

Tips for Effective Use

• Utilisation pp for hashes/arrays.
• Pair with pry-byebug for Pry’s superior REPL.
• In Rails: Requests pause in the server terminal—perfect for controller debugging.
• Always restrict to :development et :test groups.

Byebug vs. Modern Alternatives

The built-in debug gem (Ruby 3.1+) is faster, feature-richer (e.g., replay, better threads/Fibers), and the Rails 7+ default. IDEs like RubyMine or VS Code offer graphical debuggers.

Byebug shines in simplicity, familiarity, and legacy support.

Conclusion

Byebug remains a cornerstone of Ruby debugging—fast, reliable, and packed with essential features that help developers understand and fix code efficiently. Whether you’re maintaining a legacy codebase or prefer a straightforward, no-frills debugging approach, mastering Byebug can significantly boost your confidence as a Ruby developer.

À RailsCarma, our Développeurs Ruby on Rails continue to rely on proven tools like Byebug to troubleshoot complex Ruby and Ruby on Rails applications, especially in mature enterprise systems where stability and clarity matter most. This hands-on expertise allows us to diagnose issues faster and deliver cleaner, more reliable code for our clients.

For newer projects, you may also explore the debug gem, but Byebug’s strong legacy ensures it will remain a valuable part of the Ruby ecosystem for years to come. Happy debugging!