You are here
Home > development >

Debugging Ruby on Rails With byebug

The de-facto debugger for Rails is Byebug. It works with Rails were things like Pry fall short, comes recommended by the core Rails team, and is even bundled with Rails. This article will walk you through getting set up with basic Debugging Ruby on Rails With byebug.

The debugger permits the ability to understand what is going on inside a Ruby program while it executes and offers many of the traditional debugging features such as:

  • Stepping: Running your program one line at a time.
  • Breaking: Pausing the program at some event or specified instruction, to examine the current state.
  • Evaluating: Basic REPL functionality, although pry does a better job at that.
  • Tracking: Keeping track of the different values of your variables or the different lines executed by your program.



  • Required: MRI 2.5.0 or higher.
  • Recommended: MRI 2.6.4 or higher (MRI 2.6.0 to 2.6.3 contain a regression causing unbalanced call/return events in some cases, breaking the next command).

Setting up

Version 5.0 of Rails comes with Byebug, but if you don’t have it, you can simply add the following to your Gemfile and run bundle:

gem "byebug"

or you can also simply

gem install byebug

Alternatively, if you use bundler:

bundle add byebug --group "development, test"

You can enter byebug in a similar fashion to other debuggers: pick a point in the code at which to jump into the debugger and add:




for example,

If you were debugging Rails, you would add byebug to your code:

and run rails server

bin/rails s

Once the execution gets to your byebug command, you will receive a debugging prompt.

You can debug code from the command prompt now

Command-line options

  • f (frame) – shows information about the currently executing stack frame, including both the file and line number. This also takes an integer, so you can see what will be executing in a couple of stack frames time, for example: f 2.
  • th (thread) – allows you to check information relating to, and to interact with threads. liststart and stop have all been helpful to me in the past. Additionally, you can pass a number to switch context to the corresponding thread.
  • hist (history) – will show all of your history. This (helpfully) persists between debugging sessions.
  • save – saves byebug history into a file (you can specify this with an argument, or let it default to .byebug_save in your home directory)
  • source – This is one of the best features for power users, in my opinion – if you have a bunch of Byebug commands, aliases or custom functions that you find yourself using frequently, you can source them directly into your debugging session.
  • irb – This will kick you into an irb session.
  • bt (backtrace) – This displays the backtrace.
  • info – This is one of the most versatile commands. Pass argsvariablesinstance_variablesglobal_variableslocals to it for more information about what is in scope. file will show you which file is currently executing, a line count, a list of the breakpoint positions, a last modified time, and an SHA1 digest. This is absolutely invaluable when you aren’t sure if your changes have propagated.

Words of wisdom

The excellent pry-byebug adds nextstepfinishcontinue, and break commands to pry using byebug. Additionally, one of my default gems on any project in which I’m using minitest, is the fantastic minitest-byebug. This will kick you straight into a Byebug session in the event that one of your tests fails. With a little work, you can make this play nicely with Guard, to create a formidable unit testing tool. Finally, for you Sublime users, there is sublime_debugger, which wraps Byebug in a neat little GUI. Enjoy Debugging Ruby on Rails With byebug.

Komal Swami
Tech Explorer

One thought on “Debugging Ruby on Rails With byebug

Leave a Reply