This library provides debugging functionality to Ruby.

To add a debugger to your code, start by requiring debug in your program:

def say(word)
  require 'debug'
  puts word

This will cause Ruby to interrupt execution and show a prompt when the say method is run.

Once you’re inside the prompt, you can start debugging your program.

(rdb:1) p word


The following is a list of common functionalities that the debugger provides.

In general, a debugger is used to find bugs in your program, which often means pausing execution and inspecting variables at some point in time.

Let’s look at an example:

def my_method(foo)
  require 'debug'
  foo = get_foo if foo.nil?
  raise if foo.nil?

When you run this program, the debugger will kick in just before the foo assignment.

(rdb:1) p foo

In this example, it’d be interesting to move to the next line and inspect the value of foo again. You can do that by pressing n:

(rdb:1) n # goes to next line
(rdb:1) p foo

You now know that the original value of foo was nil, and that it still was nil after calling get_foo.

Other useful commands for navigating through your code are:

  • c: Runs the program until it either exists or encounters another breakpoint. You usually press c when you are finished debugging your program and want to resume its execution.

  • s: Steps into method definition. In the previous example, s would take you inside the method definition of get_foo.

  • r: Restart the program.
  • q: Quit the program.

Inspecting variables

You can use the debugger to easily inspect both local and global variables. We’ve seen how to inspect local variables before:

(rdb:1) p my_arg

You can also pretty print the result of variables or expressions:

(rdb:1) pp %w{a very long long array containing many words}

You can list all local variables with +v l+:

(rdb:1) v l
  foo => "hello"

Similarly, you can show all global variables with +v g+:

(rdb:1) v g
  all global variables

Finally, you can omit p if you simply want to evaluate a variable or expression

(rdb:1) 5**2

Staying out of trouble

Make sure you remove every instance of +require ‘debug’+ before shipping your code. Failing to do so may result in your program hanging unpredictably.

Debug is not available in safe mode.

debug Reference

Alternative debugging/breakpoint solutions

Since Ruby 2.5.0, there is the Binding#irb method, which enters an IRB session at the point of call.

Third-party libraries:

  • byebug is currently most used and freature-rich Ruby debugger;
  • pry interactive console (alternative to IRB) also provides #pry method.