# pry-byebug: step-by-step debugging and stack navigation inside Pry

> pry-byebug extends the Pry REPL with byebug's stepping engine, adding break, step, next and stack navigation commands to any session opened with binding.pry. It requires MRI 3.2.0 or higher, and all documented alternatives are incompatible with it.

**deivid-rodriguez/pry-byebug** — Step-by-step debugging and stack navigation in Pry

- Repository: https://github.com/deivid-rodriguez/pry-byebug
- Stars: 2,031 · Forks: 147
- Language: Ruby
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/deivid-rodriguez-pry-byebug

## What pry-byebug adds to a plain Pry session

Pry is an interactive console that replaces IRB, offering syntax highlighting, introspection, and a plugin command system. What it leaves out is any ability to pause execution and walk through code line by line. pry-byebug closes that gap by integrating byebug's stepping engine into Pry's command set, turning a binding.pry call into a proper debugging breakpoint.

No special launch mode is needed. Place binding.pry anywhere in your Ruby code, start the application normally, and execution stops at that line. From there, the Pry session gives you the standard command set plus nine new commands provided by this gem. Step-by-step debugging covers step, next, finish, continue and break. Stack navigation covers backtrace, up, down and frame.

The project is a fork of pry-debugger, the older gem that brought stepping to Pry on MRI 1.9.3. pry-byebug replaces it for current Ruby runtimes, swapping the older debugger backend for byebug. Patches and bug reports are welcome; the repository root holds a CONTRIBUTING.md that links to a Getting Started with Development guide.

## The MRI 3.2.0 floor and where the gem lives in your Gemfile

Install pry-byebug by adding the gem declaration to your Gemfile:

```ruby
gem 'pry-byebug'
```

Then run Bundler:

```console
bundle install
```

The requirement is MRI 3.2.0 or higher. MRI is the reference C implementation of Ruby, also called CRuby. Other Ruby implementations are not supported by this version of the gem.

One placement detail the README makes explicit: include the gem globally or inside the :test group when you plan to use it to debug tests. If the gem appears only in the :development group, it will not be loaded during a test run. Execution will pause at binding.pry and open a session, but the stepping commands will be missing, which is a silent failure that is easy to miss on first setup.

Version v3.12.0 was published on 2026-01-16. The last push to the repository was on 2026-05-18.

## step, next, finish and continue each advance execution differently

The four stepping commands cover different levels of execution movement. When the current line contains a method call, step descends into that method body. On a plain statement with no call, it moves forward one line. next stays in the same stack frame and advances to the following statement, treating any method call on the current line as a unit that runs to completion. An integer argument to either command repeats it that many times: passing 3 to step fires it three times in sequence.

The README illustrates the difference:

```ruby
def some_method
  puts 'Hello World' # Run 'step' in the console to move here
end

binding.pry
some_method          # Execution will stop here.
puts 'Goodbye World' # Run 'next' in the console to move here.
```

Running step at the binding.pry line descends into some_method. Running next instead skips the method body entirely and moves to puts 'Goodbye World'.

finish runs the rest of the current method and returns control to the call site, which is useful when you have stepped several levels deep and want to resurface quickly. continue releases the session and lets program execution resume. If no further breakpoints are active, the program runs to completion.

## backtrace, up, down and frame for reading the call stack

Four commands address the call stack rather than forward execution. backtrace prints every frame in the current call stack, each prefixed with a number on the left. Those numbers feed the frame command: frame 5 jumps directly to the fifth listed frame. Called without an argument, frame prints the current frame, which is useful after navigating around to confirm your position.

up moves toward the caller and down moves toward the callee. Both accept a count: down 2 moves two frames in one command, which saves reissuing down when backtrace shows the frame you need is several levels away.

Nothing in the README describes what happens if you pass frame a number outside the range of the current call stack. Test that edge before relying on it in a session where call depth varies, such as a recursive method or a long middleware chain.

## break takes a line, a method, a condition, or a management flag

The break command sets and manages breakpoints from inside a running Pry session. Its syntax covers four target types:

```ruby
break SomeClass#run            # Break at the start of `SomeClass#run`.
break Foo#bar if baz?          # Break at `Foo#bar` only if `baz?`.
break app/models/user.rb:15    # Break at line 15 in user.rb.
break 14                       # Break at line 14 in the current file.
```

Conditional breakpoints append an if clause with any Ruby expression the current scope can evaluate. Once breakpoints exist, additional flags manage them:

```ruby
break --condition 4 x > 2      # Change condition on breakpoint #4 to 'x > 2'.
break --condition 3            # Remove the condition on breakpoint #3.

break --delete 5               # Delete breakpoint #5.
break --disable-all            # Disable all breakpoints.

break                          # List all breakpoints.
break --show 2                 # Show details about breakpoint #2.
```

A bare break call prints the full table of current breakpoints. break --show N prints detail for a specific entry. For every available flag, the README directs you to run break --help from inside a Pry session, since that in-session output is the authoritative reference and the README examples do not cover every option.

## Single-letter aliases removed in 3.0 and how to restore them

Versions of pry-byebug before 3.0 provided four single-letter aliases: n for next, s for step, c for continue and f for finish. They were removed as the default because they conflict with common scratch variable names. If a session assigns a loop counter or a result to a variable named n or c, the alias would have blocked that name.

To restore the aliases, add this block to ~/.pryrc:

```ruby
if defined?(PryByebug)
  Pry.commands.alias_command 'c', 'continue'
  Pry.commands.alias_command 's', 'step'
  Pry.commands.alias_command 'n', 'next'
  Pry.commands.alias_command 'f', 'finish'
end
```

The defined?(PryByebug) guard prevents an error when the gem is absent, covering machines where the same ~/.pryrc is in use but pry-byebug is not installed.

A separate snippet adds the ability to repeat the last command by pressing Enter:

```ruby
# Hit Enter to repeat last command
Pry::Commands.command /^$/, "repeat last command" do
  pry_instance.run_command Pry.history.to_a.last
end
```

The README notes this is particularly useful with step or next, where pressing Enter advances execution without retyping the command. Both snippets go in ~/.pryrc separately; they are independent of each other.

## pry-debugger, pry-stack_explorer and pry-nav each cover a different runtime

The README names three alternatives and opens the section with an explicit warning: all three are incompatible with pry-byebug. If your project already has any of them in the Gemfile, they must be removed before pry-byebug will work.

pry-debugger targets MRI 1.9.3 or older. It is the project that pry-byebug forked from, and the README frames it as a migration aid for teams still on those earlier versions. The credits section names Gopal Patel as pry-debugger's creator, noting that pry-byebug would not exist without contributions to that earlier project. pry-stack_explorer also targets MRI 1.9.3 or older, covering stack navigation for the same audience. If you are upgrading a codebase from a 1.9.3 baseline, one of those two covers the debugging phase; after the upgrade, pry-byebug takes over.

pry-nav handles step-by-step debugging for JRuby. Since pry-byebug requires MRI, JRuby projects have no choice among these options: only pry-nav is documented for that runtime. There is no partial compatibility mode described in the README for the MRI restriction.

## MIT license, Tidelift security reporting, and recent version history

The repository carries an MIT license, with a LICENSE file at the top level. The repository root also holds a code_of_conduct.md and a CONTRIBUTING.md file, with the latter linking to a development setup guide.

Security reports go through Tidelift's contact form at tidelift.com/security. The README states that Tidelift coordinates fixes and disclosures, and that subscribers receive licensing assurances and timely security notifications for pry-byebug. The public GitHub issue tracker is not named as a security reporting path, so the Tidelift contact is the only documented route for vulnerabilities.

Three recent versions appear in the release history: v3.12.0 on 2026-01-16, v3.11.0 on 2025-03-28, and v3.10.1 on 2022-08-16. The gap between v3.10.1 and v3.11.0 was roughly two and a half years. A CHANGELOG.md file sits at the repository root and holds the per-release detail. The last push to the repository was on 2026-05-18, and the repository is not archived.

## Conclusion

pry-byebug fits Ruby developers already using Pry on MRI 3.2.0 or higher who want step-through debugging without switching tools. Skip it for JRuby projects: the README names pry-nav as the only option on that runtime. On MRI 1.9.3 or older, use pry-debugger for stepping and pry-stack_explorer for stack navigation, and remove them before adding pry-byebug when you upgrade. The alias removal in version 3.0 catches many developers coming from earlier versions or from plain byebug: before the first shared session, decide whether to restore 'n', 's', 'c' and 'f' via the ~/.pryrc snippet the README provides.

## FAQ

### How do I install pry-byebug?

Add the line gem 'pry-byebug' to your Gemfile and run bundle install. The gem requires MRI 3.2.0 or higher. Place it globally or in the :test group when you plan to debug tests, or it will not be loaded during a test run.

### What is the difference between step and next in pry-byebug?

step descends into the body of a called method when the current line contains a call, or moves forward one statement otherwise. next stays in the same stack frame, letting any method call on the current line finish before the cursor moves.

### Does pry-byebug work with JRuby?

No. pry-byebug requires MRI 3.2.0 or higher and is not supported on JRuby. The README names pry-nav as the option for step-by-step debugging on JRuby, and warns that pry-nav is incompatible with pry-byebug.

### How do I set a conditional breakpoint in pry-byebug?

Run break with an if clause inside a Pry session: for example, break Foo#bar if baz? stops at that method only when baz? evaluates to true. Any Ruby expression reachable in the current scope is valid in the condition.

### Why do the single-letter aliases n, s, c and f not work in pry-byebug?

They were removed as defaults in version 3.0 because they conflict with common scratch variable names. You can restore them by adding the alias_command calls to your ~/.pryrc file, wrapped in an if defined?(PryByebug) guard.

## Sources

- [deivid-rodriguez/pry-byebug on GitHub](https://github.com/deivid-rodriguez/pry-byebug)
- [Issues](https://github.com/deivid-rodriguez/pry-byebug/issues)
- [License: MIT](https://github.com/deivid-rodriguez/pry-byebug/blob/master/LICENSE)
- [README](https://github.com/deivid-rodriguez/pry-byebug/blob/master/README.md)
- [Releases](https://github.com/deivid-rodriguez/pry-byebug/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/deivid-rodriguez-pry-byebug