Enable xdebug on demand in your local docker environment

Reading Time: 2 minutes

Xdebug is an essential tool for me when I develop PHP applications (kudos to Derick Rethans for his dedication over the many years). Yet it admittedly slows down code execution. It gets worse when you run docker on a Mac. You are screwed if you run a really complex application like Typo3 in this setup (got a bit of a dejavu here). Wouldn’t it be cool then to only enable xdebug on demand in your local docker environment?

For example, I was working on a Typo3 project with lots of content in up to 10 languages. Without xdebug, one huge page (the dreaded ID 6) loads in 1.2 minutes, which is already really bad. But with xdebug enabled it jumps up to 6.5 minutes! You simply can’t work like that.

Surely this is an extreme example, but also on smaller pages it felt really slow with xdebug enabled. I kept it enabled though because I was too lazy to always rebuild my docker container…

Xdebug toggle script

So what I need is an easy way to enable (and disable) xdebug in my local docker setup easily. Finally, I figured out a solution that works very well for me:


This little script allows you to enable or disable xdebug in seconds using your command line:

./xdebug.sh disable

to disable it and, well you probably guessed it,

./xdebug.sh enable

to enable it again.

Absolutely no rocket science here. Under the hood, the script simply moves the docker-php-ext-xdebug.ini into a directory outside of /usr/local/etc/php/conf.d. Upon restart of the app container, PHP loads completely without xdebug. To enable it again, the file is copied back.

Some things to keep in mind:

  • It is written for the official PHP docker image on Docker Hub (using the docker-php-ext-xdebug.ini – yet this can be adapted to your needs quickly)
  • It expects the PHP service to be called “app” in docker-compose.yml. This is easily adaptable to your needs as well.

I’m not an experienced bash programmer, so there is surely room for improvement. I’m happy about suggestions to improve it!

6 thoughts on “Enable xdebug on demand in your local docker environment”

  1. Thank you very much for sharing the script. It helped a lot!

    In my case I was unable to move the ini file, there was an error “Device is busy”.

    So, I changed the version to just reset its content when disabled and back when enabled.
    Below my version, if someone needs or has the same problem.

    #!/usr/bin/env bash
    # see https://carstenwindler.de/php/enable-xdebug-on-demand-in-your-local-docker-environment/

    if [ "$#" -ne 1 ]; then
    SCRIPT_PATH=`basename "$0"`
    echo "Usage: $SCRIPT_PATH enable|disable"
    exit 1;

    # Expects service to be called app in docker-compose.yml
    SERVICE_ID=$(docker-compose ps -q web)

    if [ "$1" == "enable" ]; then
    docker exec -i $SERVICE_ID bash -c \
    '[ -f /usr/local/etc/php/disabled/docker-php-ext-xdebug.ini ] && cd /usr/local/etc/php/ && cat disabled/docker-php-ext-xdebug.ini > conf.d/docker-php-ext-xdebug.ini || echo "Xdebug already enabled"'
    docker exec -i $SERVICE_ID bash -c \
    '[ -f /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ] && cd /usr/local/etc/php/ && mkdir -p disabled/ && cp conf.d/docker-php-ext-xdebug.ini disabled/ && > conf.d/docker-php-ext-xdebug.ini || echo "Xdebug already disabled"'

    docker restart $SERVICE_ID

    docker exec -i $SERVICE_ID bash -c '$(php -m | grep -q Xdebug) && echo "Status: Xdebug ENABLED" || echo "Status: Xdebug DISABLED"'

  2. I am not good with commands can anyone guide me to where exactly I need to run this command I am on windows 10.

    Any help is much appreciated thanks in advance.

Leave a Reply

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

I accept the Privacy Policy

This site uses Akismet to reduce spam. Learn how your comment data is processed.