diff --git a/Docker/php/Dockerfile b/Docker/php/Dockerfile
index 774d89a..24aee3b 100644
--- a/Docker/php/Dockerfile
+++ b/Docker/php/Dockerfile
@@ -41,6 +41,13 @@ COPY ./rsyslog-drupal.conf /etc/rsyslog.d/drupal.conf
 # ENTRYPOINT ["sh", "-c", "service rsyslog start ; tail -f /dev/null"]
 
 COPY ./php-custom.ini /usr/local/etc/php/conf.d/php-custom.ini
+# Xdebug: off by default on CLI (drush, composer) — mode=debug alone still hooks every
+# function call and is what makes CLI commands slow, even with start_with_request=trigger.
+# Use `XDEBUG_MODE=debug XDEBUG_TRIGGER=1 drush ...` (see xdebugon/xdebugoff aliases) to debug a CLI run.
+# FPM loads an extra ini dir that restores mode=debug + start_with_request=yes for web requests.
+RUN printf "xdebug.mode=off\nxdebug.start_with_request=trigger\n" > /usr/local/etc/php/conf.d/zz-xdebug-cli.ini && \
+    mkdir -p /usr/local/etc/php/fpm-conf.d && \
+    printf "xdebug.mode=debug\nxdebug.start_with_request=yes\n" > /usr/local/etc/php/fpm-conf.d/zz-xdebug-fpm.ini
 # COPY ./php-fpm-custom.conf /usr/local/etc/php-fpm.d/php-fpm-custom.conf
 
 
@@ -64,6 +71,11 @@ RUN if getent group ${USER_GNAME} ; then groupdel ${USER_GNAME}; fi &&\
 COPY ./bashrc /home/${USER_UNAME}/.bashrc
 COPY ./inputrc /home/${USER_UNAME}/.inputrc
 
+# /home/${USER_UNAME} is a persistent named volume, so files COPYed there only apply on
+# first volume creation. Put the xdebug aliases in /etc/bash.bashrc instead, which is part
+# of the image and always sourced by interactive shells (docker exec, ssh).
+RUN printf "\n# Xdebug is off by default on CLI for speed (see zz-xdebug-cli.ini).\nalias xdebugon='export XDEBUG_MODE=debug XDEBUG_TRIGGER=1'\nalias xdebugoff='unset XDEBUG_MODE XDEBUG_TRIGGER'\n" >> /etc/bash.bashrc
+
 # https://github.com/ProgDroid/composer_update_autocomplete
 RUN mkdir /home/${USER_UNAME}/.bin
 COPY ./composer_update_autocomplete /home/${USER_UNAME}/.bin/composer_update_autocomplete
@@ -82,7 +94,7 @@ EXPOSE 22
 
 # https://stackoverflow.com/questions/36964652/ssh-in-docker-container-causes-http-404
 # use \n to make the content into multiple lines
-RUN printf "whoami\nphp-fpm -D\n/usr/sbin/sshd -D" >> /start.sh
+RUN printf "whoami\nPHP_INI_SCAN_DIR=/usr/local/etc/php/conf.d:/usr/local/etc/php/fpm-conf.d php-fpm -D\n/usr/sbin/sshd -D" >> /start.sh
 RUN chmod +x /start.sh
 CMD ["/start.sh"]
 
diff --git a/README.md b/README.md
index 6e77209..e8196df 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,30 @@ sudo docker exec -it materiod8_php_1 bash
 ```
 once inside the php container in /var/www/html you can use drush as usual
 
+### Xdebug
+
+Xdebug is installed in the php container, listening for your IDE on `host.docker.internal:9001` (see `ressources/xdebug.ini`, `.vscode/launch.json` in `public_html`).
+
+Web and CLI behave differently on purpose, because leaving `xdebug.mode=debug` on all the time makes every `drush`/`composer` command noticeably slower (Xdebug hooks every function call as soon as the mode is active, whether or not a debugger actually connects):
+
+- **Browser requests (php-fpm)**: Xdebug is always on (`xdebug.mode=debug`, `xdebug.start_with_request=yes`). Just start listening in your IDE and load the page, no trigger needed.
+- **CLI (`drush`, `composer`, ...)**: Xdebug is **off by default** (`xdebug.mode=off`) so commands stay fast. To debug a specific command, turn it on for the current shell first:
+  ```
+  xdebugon
+  drush some:command
+  xdebugoff
+  ```
+  `xdebugon`/`xdebugoff` are shell aliases defined in `/etc/bash.bashrc` inside the php container (they set/unset `XDEBUG_MODE=debug` and `XDEBUG_TRIGGER=1`). You can also do it inline for a single command:
+  ```
+  XDEBUG_MODE=debug XDEBUG_TRIGGER=1 drush some:command
+  ```
+
+This split is implemented as two extra ini files loaded per-SAPI, see `Docker/php/Dockerfile`:
+- `/usr/local/etc/php/conf.d/zz-xdebug-cli.ini` → loaded by both CLI and php-fpm (default conf.d), sets `xdebug.mode=off`.
+- `/usr/local/etc/php/fpm-conf.d/zz-xdebug-fpm.ini` → only loaded by php-fpm (via `PHP_INI_SCAN_DIR` in `/start.sh`), overrides back to `xdebug.mode=debug` for web requests.
+
+If you change any of these files, rebuild the php image (`make buildphp`) and recreate the container (`make up`) — do not use raw `docker-compose up`, it won't pick up `USER_UID`/`USER_GID` and the container will run as root (see Makefile section below).
+
 ### gulp
 Dev process needs gulp to run in:
 - public_html/sites/all/modules/custom/materio/