Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Docker For Mac Host Address Alias To Enable PHP XDebug ( Trick)

Docker (Mac) De-facto Standard Host Address Alias

This launchd script will ensure that your Docker environment on your Mac will have as an alias on your loopback device ( The command being run is ifconfig lo0 alias

Once your machine has a well known IP address, your PHP container will then be able to connect to it, specifically XDebug can connect to it at the configured xdebug.remote_host.

Installation Of IP Alias (This survives reboot)

Copy/Paste the following in terminal with sudo (must be root as the target directory is owned by root)...

sudo curl -o /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

Or copy the above Plist file to /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

Next and every successive reboot will ensure your lo0 will have the proper ip address.

Finally, make sure to configure your xdebug correctly. However you get your xdebug.remote_host into the container, ensure it has similar settings:

It is also useful to pass the following environment variable into your container:


PHPStorm will use localhost as the server name when you setup the Preferences > PHP > Debugging profile.


Because docker.local is gone. This seems to be the easiest way to setup xdebug to connect back to your IDE running on your host. Similarly, this is a solution for any kind of situations where a container needs to connect back to the host container at a known ip address.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Ran manually, confirmed working. TYSM.

DrNgo commented Sep 22, 2016

Ran this as well, confirmed working. Thanks so much for this solution!

Thanks a lot for this solution!

ababushkin commented Oct 15, 2016

Can you please post your docker-compose configuration file for the PHP and nginx containers? I can't seem to get this to work still :(

Never mind, my container had the wrong configuration (reboot caused me to lose my local state).

Thanks this is working without issues 👍

jkuma commented Jan 7, 2017

Working like a charm ! Many thanks sir 👍

Worked! Thanks

fjmiguel commented Jan 27, 2017

Thank you so much! Great solution!

Thank you so much, IT WORKS.

It works, thanks!

starlocke commented May 17, 2017

Sanity checking:

  • less /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

To run this straightaway (without a reboot) run the following:


ralphschindler commented Jul 28, 2017

^ Good advice, and good blog post. Excellent @starlocke & @ashsmith. Thanks!

J7mbo commented Sep 25, 2017

I've used this for a while, except that I found xdebug.remote_autostart=1 completely messes with Composer. Sometimes, Composer in the docker container just doesn't even work with it enabled and hangs.

As a result, I have to set the configuration to xdebug.remote_autostart=0 and pass the argument to my php script with -d instead:

php -dxdebug.remote_autostart=1 /path/to/script.php

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment