Setting up Xdebug with NetBeans on Windows, with a Remote Apache Server

I fought with Xdebug and NetBeans enough to necessitate a post about it, if only so I don’t forget.

Most Xdebug/NetBeans tutorial assume that you’re doing development on your local machine. That’s a fine setup, but not what I was needed for this project.


Server: A typical Linux server — Debian, Apache2 and PHP.

Debugger: Xdebug

Client: Firefox on Windows, etc.

IDE: NetBeans 7.1.1

Other Tools: PuTTY

Setting Up Xdebug

Install xdebug with the command:

pecl install xdebug

The final lines of output should say something like:

Build process completed successfully
Installing '/usr/lib/php5/20090626/'
install ok: channel://

Take note of the install path, /usr/lib/php5/20090626/, in this case. Now add the following to your PHP configuration. I created a new .ini file at


Its contents should be as follows (change the zend_extension to match the install path found above):

zend_extension = "/usr/lib/php5/20090626/"

xdebug.remote_enable = on

; Most users won't want autostart. More on this later.
; xdebug.remote_autostart = on
xdebug.remote_autostart = off
xdebug.remote_handler = dbgp
xdebug.remote_port = 9000
xdebug.remote_server = localhost
xdebug.remote_mode = req

; Most users won't want a hard coded idekey. More on this later.
; xdebug.idekey = netbeans-xdebug
output_buffering = off

xdebug.remote_log = "/var/log/xdebug.log"

Restart Apache to complete the installation.

xdebug.remote_server = localhost. Localhost? Wait a second, I thought this was for working with a remote server? Yes, but xdebug needs to be able to connect to your computer. The easy option is to have xdebug connect to the server’s localhost, then use PuTTY to create an SSH tunnel so that NetBeans can listen on your computer’s localhost.

The harder option is to configure your home or office router to forward port 9000 to you, be sure to never change your IP address, and open port 9000 on your Windows firewall. You could use xdebug.remote_connect_back so that xdebug would connect to whichever IP made the web request, but then someone who isn’t you could access your code.

In my opinion, the SSH tunneling is the cleanest option. You can use it anywhere that you have SSH access, xdebug access is restricted to those who have SSH access and you don’t have to worry about your IP address changing.

Creating an SSH Tunnel for Xdebug

Using PuTTY.exe create and save a new SSH session which connects to your server. In this saved session configure a tunnel. Set the source port to 9000, the destination to localhost:9000, and choose the Remove and Auto radio buttons. Click the Add button to add that port forwarding configuration, then save that session to use every time you want to use xdebug.

PuTTY xdebug SSH tunnel
PuTTY xdebug SSH tunnel

Go ahead and connect to that saved PuTTY session now. Once you’re connected to your server you should be able to run netstat to verify that it’s working correctly. It should show something like this:

netstat -a -n | grep 9000
tcp        0      0*               LISTEN
tcp6       0      0 ::1:9000                :::*                    LISTEN

Setting up NetBeans

Set up your NetBeans project like you usually would. Verify that the PHP Debugging Settings (In the Tools->Options menu) are set to debugger port 9000, and the Session ID of netbeans-xdebug. I had problems with the Watches and Balloon Evaluation options. YMMV.

NetBeans Debugging Settings
NetBeans Debugging Settings

In your project properties (Right click your project, click Properties) edit the Run Configuration’s Advanced properties. Select “Do Not Open Web Browser”.

A Note on Path Mappings

Based on the tutorials I read, most users don’t seem to need Path Mappings. NetBeans seems to figure out the path based on the upload directory, the URL and the Web Root settings.  That didn’t work for me. I needed Path Mapping because I had a symlink on the server.

PHP (and so Xdebug) dereferences symlinks and NetBeans needs the mapping between the dereferenced path on the server and the local sources directory.

This is a known issue, but not very well known. Symptoms that you need to  use mapping include NetBeans not breaking in symlinked files, NetBeans not opening the file or not opening the correct file when Xdebug connection is made. Or it may work only if you use “Debug File” instead of “Debug Project”.

 Debugging With Xdebug and NetBeans

Here’s where you have some options. The manual way to active Xdebug is to append XDEBUG_SESSION_START=netbeans-xdebug to your query string when you request a page in the browser. With the current setup, this should work. Go ahead and test it.

Choose Debug -> Debug Project from the NetBeans menu. Then, in your browser, go to (replacing the URL with your own, of course).

If that doesn’t work then something isn’t set up correctly. It might be NetBeans, it might be Xdebug, it might be the SSH tunnel. Figure it out, get it fixed, then keep reading (you can leave comments here, and I’ll help as I can. Google is pretty helpful too).

If that does work, then GREAT!

Now you have some options.

Browser Extensions

Firefox and Chrome both have Xdebug extensions that set the XDEBUG_SESSION_START parameter in the http headers. This makes it so you don’t have to type it yourself.  Yay Firefox. Yay Chrome.

Always Auto-start Xdebug

If you are testing embedded webkit, or from mobile devices, or something else that’s not a normal browser, then appending XDEBUG_SESSION_START is going to be difficult. This is where I send you back to your xdebug.ini file to change some settings. If you need to debug requests from these sorts of devices, then you’re going to want to edit xdebug.ini and set:

xdebug.remote_autostart = on
xdebug.idekey = netbeans-xdebug

This will cause Xdebug to attempt to connect on port 9000 on every request. The idekey setting is so that NetBeans will know that the connection is for it.

Other PHP Debugging Tools

If you are looking for good PHP debugging tools, you may also want to try out KCacheGrind which will profile your code giving you an idea what’s taking up time and memory. HipHop-PHP, a tool from Facebook of all places, compiles PHP into C++. In the process it spits out all sorts of helpful errors and notices that will help you find errors in your code.

That concludes one more NetBeans Xdebug tutorial that will hopefully get you that much closer to doing some serious PHP debugging. Happy coding!

This entry was posted in Computers, Programming, Something Interesting and tagged , , , , , , . Bookmark the permalink.

19 Responses to Setting up Xdebug with NetBeans on Windows, with a Remote Apache Server

  1. Josh Wilson says:

    Thank you! I was going crazy trying to get this to work. The tip about setting xdebug.remote_server = localhost is what I was missing. I assumed it should be my remote address.

  2. medowlock says:

    Perfect ! Just perfect ! This is the only article I found that start from the beginning and explains CLEARLY every step. Also, the screenshot from Netbeans\Advanced Web Configuration with how the paths should be set is pure gold !

  3. FlyOn says:

    Great! Couldn’t get it to work behind a router. Have been looking for hours…. SSH tunnels were the key! THANK YOU!

  4. YOLO says:

    You saved my life, I was so dumb that forgotten to open port in my firewall and spent 2 hours configuring my linux installation.

  5. Krishna says:

    Thanks a lot for helping us out.
    Yours is the most reliable explanation for the remote debugging.

  6. shashi says:

    if your vm has host only IP its safe to add
    this will let u connection from any ip (xdebug 2.1 and above only)
    instead of
    remote_host =blah blah
    and you dont need a tunnel open or worry about your ip changing

    ….. this thing was a pain…

  7. James says:

    Hi All

    Stuporglue, thanks a bunch for this post, I’d have never worked out the putty trick without it. Send me your stackoverflow username and I will systematically vote up all your posts by way of payment.

    Literally, as dumb as this will seem, I’m leaving it just in case it helps anybody, after a day of frustration the debugger came to life when:

    After changing the port number in Tools->Options->PHP, I clicked ‘apply’ and then ‘OK’, not just ‘OK’ directly.

    At least its over now…

    • stuporglue says:

      Send me your stackoverflow username and I will systematically vote up all your posts by way of payment.

      Best payment offer ever!

      I’m stuporglue just about everywhere, but I’m not on SO much, so I’ll just let you have this solution for free.

  8. Ramesh says:

    I want to debug my remote machine where we have hosted our web application. Please convey i have to install Xdebug in remote server or in local machine

  9. Pierre says:

    Thanks a million for that clean tuto and this alternative way (ssh / localhost).
    You have gratefull greetings from France :)

    Tell me if i’m wrong but :
    the way you give is more handy to access the debug mode project from anywhere no ?
    And if i want to give access to other people from outside, i just have to create other linux/ssh accounts , and route the ssh port of my router ?

    Or maybe this would be to much insecure and you would suggest a vpn as well.
    but a vpn AND ssh its like a tunnel inside a tunnel no ?

    Thanks a lot

    • stuporglue says:

      the way you give is more handy to access the debug mode project from anywhere no ?

      I prefer this way, yes. I think it’s easier than dealing with firewall configurations.

      And if i want to give access to other people from outside, i just have to create other linux/ssh accounts , and route the ssh port of my router ?

      Yes. I’m not sure what would happen if two people tried to debug at the same time. Probably one person wouldn’t be able to connect to the debug port.

      Or maybe this would be to much insecure and you would suggest a vpn as well.
      but a vpn AND ssh its like a tunnel inside a tunnel no ?

      VPN is good if you don’t want to expose the SSH port to the world. Personally I configure SSH to use a non-standard port, only allow key-based authentication and disable SSH for root. For my sites I think this is sufficient. Other sites might need more security.

  10. Nick says:

    In Netbeans 8.1, « Project Properties » → « Run Configuration », I had to choose :
    Run As : Local Web Site (running on local webserver)
    Project URL : http://remote_adress/

    Yes, « Run As » local, and « Project URL » remote.

    And do « Advanced » « Path Mapping » as mentioned in the instructions.

    Then, « Debug »→ « Debug Project », or click on the debug icon, started the debugger.

  11. Slava says:

    Originally I have configure port forwarding in VirtualBox (TCP port 9000 from vm to host).
    This doesn’t work with NetBeans and debugger can’t connect (port is occupied)

    After I have setup ssh tunnel and remove port forwarding in VirtualBox – debugger start working.

    Thank you, great post!

  12. Stephen says:

    Agree with all praise above – wasted a couple of days fighting port redirection, firewalls to no avail… then tried the SSH tunneling with putty, without initial success – UNTIL – I read the xdebug.remote_server = localhost!! Fantastic – worked perfectly first time! A huge Thankyou!! btw – I am using Komodo and all worked a treat. Best to set URI mapping with edit->preferences->MappedURIs’\ (Komodo version 10) otherwise the mapping question seems to pop up each time one runs the website under test – although all seems to work fine even if you cancel window that pops up…..

    Ideally, as a networking intellectual exercise, I would like to get all the port redirection stuff working…. but so relieved to get the debugging environment up and running!

    Once again – a big thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *