debug
A modern debugger for Ruby (MRI) 2.7+ with remote debugging, VSCode/Chrome integration, and performance optimizations.
What is debug?
debug.rb is the official debugging library for Ruby (MRI) 2.7 and later, replacing the older standard library debugger. It provides a fast, feature-rich debugging environment with support for remote debugging, integration with tools like VSCode and Chrome DevTools, and modern capabilities like recording/replay.
Ruby developers who need a powerful, modern debugger for applications running locally, in containers, or as daemons, especially those transitioning from byebug or the legacy debug.rb.
Developers choose debug.rb for its performance (no overhead when not debugging), native remote debugging support, and seamless integration with popular IDEs and browsers, making it a versatile tool for both local and complex deployment scenarios.
Overview
Debugging functionality for Ruby
Use Cases
Best For
- Debugging Ruby applications running in Docker containers without a TTY
- Remote debugging of daemonized Ruby processes
- Using VSCode as a graphical debugger for Ruby code
- Debugging with Chrome DevTools for a browser-based interface
- Setting breakpoints via `binding.break` similar to `binding.pry`
- Recording and replaying debugging sessions for complex issues
Not Ideal For
- Projects locked on Ruby versions older than 2.7, as debug.rb requires MRI 2.7+ and won't work with legacy systems.
- Teams deeply entrenched in byebug with custom plugins or workflows, as migration might disrupt established debugging habits.
- Environments with stringent security requirements where unencrypted remote debugging over TCP/IP poses an unacceptable risk.
- Simple, interactive debugging needs where lightweight tools like binding.pry or irb suffice without the overhead of a full debugger suite.
Pros & Cons
Pros
When not actively stepping or at breakpoints, debug.rb incurs no performance penalty, unlike the old debug.rb that used slow set_trace_func.
Supports UNIX domain sockets and TCP/IP out of the box, enabling seamless debugging of daemons, Docker containers, and non-TTY environments without third-party hacks.
Integrates directly with VSCode via the vscode-rdbg extension and Chrome DevTools, providing graphical debugging interfaces that rival other languages.
Can be invoked via the rdbg command, by requiring libraries, or using binding.break similar to binding.pry, catering to different workflows and environments.
Cons
The README explicitly lists Ractor support as 'TODO', limiting its usefulness for Ruby 3's advanced concurrency features in production debugging scenarios.
All messages between debugger and debuggee are not encrypted, as noted in the documentation, making remote debugging risky over untrusted networks without additional safeguards.
With over 30 environment variables and config options, setting up advanced features like remote ports or initial scripts can be overwhelming and error-prone for new users.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.