When you’re banging your head against the wall trying to fix a bug, the last thing you want is having to stop and learn how to use the debugging tool.

The last time this happened, you added require 'pry' on a ruby file but quickly realized you didn’t know the available commands. What’s that noise? Oh, it’s the sound of more frustration being added to your day!

If only there was a way for you to quickly learn how to use Pry… Well, there is now! If you always wanted to improve your debugging skills but couldn’t find the time or guidance to do it on your own, this post is for you.

By the end of this guide, you’ll be able to use Pry effectively. Say goodbye to hours of googling and manually creating instances of objects to be able to debug. Say hi to your new debugging skills with Pry😎. Let’s go!

This is based on Justin Gordon’s Rails Conf 2021 talk Implicit to Explicit: Decoding Ruby’s Magical Syntax.

Getting Started with Pry in 5 minutes

These examples work on a Ruby on Rails application. However, Pry works with any Ruby file.

Install pry

  1. Add the following lines to your Gemfile. To install the auxiliary gems, remove the comments after # Pry Auxiliary Gems. You can also gem install each one of them if you don’t want to add them to the Gemfile.
group :development, :test do
  # Basic Pry Setup
  gem 'awesome_print' # pretty print ruby objects
  gem 'pry' # Console with powerful introspection capabilities
  gem 'pry-byebug' # Integrates pry with byebug
  gem 'pry-doc' # Provide MRI Core documentation
  gem 'pry-rails' # Causes rails console to open pry. `DISABLE_PRY_RAILS=1 rails c` can still open with IRB
  
  # Auxiliary Gems
  # gem 'pry-rescue' # Start a pry session whenever something goes wrong
  # gem 'pry-theme' # An easy way to customize Pry colors via theme files
  # gem 'pry-stack_explorer' # Allows navigating Pry call stack
  # gem 'binding_of_caller' # To evaluate code from a higher up call stack context
end
  1. Run bundle install
  2. On your terminal, run pry to check you have everything set up. If you’ve got a Pry REPL running, you’re good to go.

Configure pry

To get the .pryrc aliases working, you need to run the following command:

$ curl https://gist.githubusercontent.com/justin808/1fe1dfbecc00a18e7f2a/raw/e0ea4dd77d34724ee3bbc8345c244e7e78a21d7b/.pryrc > $HOME/.pryrc

It will copy this .pryrc file that configures and styles the pry console. If you want to do it manually, save the linked ~/.pryrc file in your home folder.

How to use Pry

Add binding.pry to any ruby file to start the debugger. For example:

class Account < ApplicationRecord
  def self.active
    binding.pry # -< add this where you want to debug
    where(archived: false)
  end
end

When this line of code gets executed, a pry REPL will open.

Pry commands

Now, to the fun part!

Pry has tons of commands and features but the ones below are enough for you to get started:

!!!                     # run it anytime you want to exit the program.
help                    # overview of pry features
help alias              # list of commands aliases
help whereami           # see the docs for *any* pry command, on this case, whereami
#### code browsing
w                       # whereami
@                       # alias to whereami - describes the current location on the source code
$                       # displays the code's location line, the object's owner, method visibility, and length
@ 5                     # displays the current location and the 5 previous and posterior lines of code
h                       # displays the last 20 commands
$ some_method           # display the some_method implementation
show-source method_name # shows the source code for a given method. Example: show-source User.create
find-method to_a        # finds method to_a
play -l line_number     # executes line_number in the current context
self                    # make Ruby's magical syntax more explicit
pp(obj)                 # pretty-print the object passed in
#### state navigation
cd SomeModule           # changes context to module or class
ls -m                   # lists methods in the context
cd ..                   # move context back up
#### stepping
b                       # break
s                       # step
c                       # continue
n                       # next line

Note: If you’re using Puma, you’ll get multiple threads running. Check out Justin’s thread about running Puma for Debugging with Pry to learn how to handle that.

Pry Debug Cheat Sheet

Download this Cheat Sheet to help your future debugger self:

Getting Started with Pry in 5 minutes

Share this post if you found it helpful. Let us know if you have other cool Pry tips to share. Enjoy!

By the way, we watched Justin’s talk together with other developers in a previous Watch Party event. Everyone decided to improve their debugging skills.

If you’d like to join a small group of like-minded developers and learn together, join the hexdevs events page and we’ll let you know when we host another Watch Party. We’ll send a wrap-up doc just like this one to share what we’ve learned even if you can’t join the live session.