Xdebug: the PHP step debugger, how it installs, and where it stops being the right tool

What Xdebug solves, and who it is actually for

PHP's own error output gives you a message and a line number. It does not give you a call stack you can walk, a variable view at an arbitrary breakpoint, or a profile of where the time went. Xdebug fills that gap. The README describes it as "a debugging tool for PHP" that provides step-debugging plus "a whole range of development helpers, such as stack traces, a code profiler, features to dump the full execution of your script to a file, and more".

That list defines the audience. Xdebug is for people writing or maintaining PHP: application developers chasing a wrong value through a framework's dispatch chain, maintainers of a library who need to see what a caller passed in, and anyone profiling a slow request. It is not a runtime dependency you ship to users, and the README's framing is development-oriented throughout. The step debugger in particular assumes a second process. The documentation states that the step debugger "requires an IDE (client), of which there are many available", so the extension alone does not give you a debugging session; it gives you the server side of one.

The DBGp client model behind xdebug.mode=debug

The architectural decision that shapes everything else is that Xdebug is a PHP extension written in C, loaded into the PHP process, not a separate program that inspects your code from outside. It hooks into the engine, which is why it can see function arguments and local variables that a pure userland tool cannot. The README is explicit that contributing means working in C with "extensive knowledge of PHP's internals".

On top of that, features are gated. "Most features in Xdebug have to be opted in into. Each feature has a specific opt-in." The README's own example is the step debugger, which needs xdebug.remote_enable=1 in the configuration file. This is a deliberate trade-off: loading an extension that instruments execution has a cost, and leaving everything off by default keeps an installed Xdebug from changing the behaviour of code that does not ask for it. The price is that a fresh install does nothing visible until you configure it, which is where most first-time confusion comes from.

When the step debugger is on, the flow is: your PHP process hits a breakpoint condition, opens a connection to a listening client, and speaks DBGp over that connection. The IDE is the client. That is why the same extension works with several different editors, and why nothing happens if no client is listening.

Installing Xdebug on Linux, macOS or Windows

The README gives two supported routes. On most Linux distributions you install through the distribution's package manager, where the package is most often named php-xdebug. Everywhere else, including macOS and Windows, the documented route is the PIE installer:

pie install xdebug/xdebug

The README notes that installation requires the pie tool unless your Linux distribution has an Xdebug package. The prerequisites section is short and worth reading before you start: Xdebug "requires a supported version of PHP", with a link to PHP's supported-versions page. If your PHP is past end of life, that is the first thing to resolve, not the Xdebug configuration.

The README points to https://xdebug.org/docs/install for the longer instructions, and that page is where the per-platform detail lives. Nothing in the repository README describes an uninstall procedure, so plan for the extension being present in php.ini once you have added it.

Turning on the step debugger and getting a first breakpoint

After installation, the configuration file is where the work happens. The README's example for enabling step debugging is this setting:

xdebug.remote_enable=1

With that in place and an IDE client listening, a request that reaches a breakpoint will pause and hand control to the editor. The README does not spell out the client-side setup because it is editor-specific; it links to the list of available clients instead.

The README also points at the full settings reference at https://xdebug.org/docs/all_settings, and says there are "over a hundred settings and many functions documented". That number is the honest summary of the configuration surface: the two or three settings most tutorials show are a fraction of what exists, and the documentation site, not the README, is the reference you will actually keep open.

One more thing from the repository layout: there is an xdebug.ini file at the top level. It is part of the project's own files rather than a template the README tells you to copy, so treat the documentation site as the source for what your php.ini should contain.

Where Xdebug is the wrong tool

The clearest limitation is the client requirement. If you enable the step debugger and no IDE is listening, you have added a configuration that expects a peer process that is not there. The README frames the IDE as a requirement, not an option, for that feature.

The second limitation is the distribution model. Xdebug is a C extension. On shared hosting, or on any platform where you cannot install a PHP extension or rebuild PHP, you cannot run it at all. The README's fallback is a distribution package, and not every distribution ships one. If neither route is open to you, the tool is simply unavailable, and no amount of configuration will change that.

The third is the licence question, covered below. If your organisation has a policy of accepting only OSI-approved licences, the README's own wording about the Xdebug License deserves a look before you standardise on it.

Finally, Xdebug is a development instrument. The README describes the profiler and the execution dump as development helpers, and the step debugger as something that needs a client. Using it as a production observability layer inverts what it was built for.

How Xdebug differs from Blackfire and similar profilers

The comparison worth making is with a profiling service such as Blackfire. Both tell you where time goes in a PHP request, but the mechanism differs. Xdebug is an extension you install yourself, configured through php.ini, with the profiler as one of several opt-in features alongside step debugging and stack traces. A hosted profiler typically works through its own agent and a service that stores and compares profiles across runs.

That difference decides the use case. If you want a breakpoint, a variable view and a stack trace inside your editor while you work, Xdebug is the direct answer, and a profile store is not. If you want to compare profiles from a staging environment over weeks and track a regression across deploys, a service built around storing profiles is doing something Xdebug's file output does not attempt. They are not substitutes; the README's profiler writes output for you to read, and it does not claim to be a longitudinal performance platform.

For the narrower question of stack traces, PHP's own exception traces cover the common case. Xdebug's value is in the cases where they do not: a wrong value deep in a call chain, or a request you need to step through rather than infer.

Maintenance, releases and what the licence says

The repository is not archived, and the last push was on 2026-09-08. The most recent release is 3.6.0alpha1, dated 2026-09-08, which is a pre-release; the newest stable release listed is 3.5.3 from 2026-06-08. If you need stability, 3.5.3 is the version to start from, and 3.6.0alpha1 is the one to test against if you are willing to run an alpha.

The upgrade cost is mostly configuration drift, not code changes on your side. Because features are opt-in through settings, an upgrade can change defaults or rename settings, and the README points you at the settings reference rather than promising stability. That is the thing to check in a release before upgrading a team's shared php.ini.

On licensing: the README states that Xdebug is released under The Xdebug License, which "is based on The PHP License". It also states plainly that it is "an Open Source license (though not explicitly endorsed by the Open Source Initiative)". That parenthetical is the part to take to whoever reviews licences in your organisation. This is a description of what the README says, not legal advice, and the LICENSE file in the repository is the text to read.

Editorial conclusion

Adopt Xdebug if you develop or maintain PHP code and want a real step debugger, stack traces or a profiler wired into your editor, and if you can install a C extension on every machine where you need it. Do not adopt it as a production dependency: the README says most features must be opted in, and the step debugger expects an IDE client to be listening. Before you commit, verify three things in your own environment: that your PHP version is still on the supported list, that your distribution actually ships a php-xdebug package or that pie can build against your PHP headers, and that your editor speaks DBGp so the xdebug.mode=debug setting has somewhere to connect. Read the LICENSE file itself rather than assuming the PHP License wording is identical.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. xdebug/xdebug on GitHub