diff --git a/docs/gallery-dl.md b/docs/gallery-dl.md
index 09af9ac..7507dc1 100644
--- a/docs/gallery-dl.md
+++ b/docs/gallery-dl.md
@@ -426,7 +426,23 @@ Re-running with those recovered both videos and produced **0 failures and 0
 
 Without it, gallery-dl logs `Cannot import yt-dlp or youtube-dl` and falls back
 to a progressive URL for DASH videos. The fallback mostly works but is what the
-429s hit hardest. `pipx install yt-dlp` on the fetch host.
+429s hit hardest.
+
+**`pipx install yt-dlp` does not work** — it was the advice here until
+2026-08-20, and it is wrong. It gives yt-dlp its own venv, so the binary lands
+on `PATH` while gallery-dl, in a *different* venv, still cannot `import yt_dlp`.
+The symptom is that everything looks installed and the log keeps saying
+`Cannot import yt-dlp`. gallery-dl needs it importable, not runnable:
+
+```sh
+pipx inject gallery-dl yt-dlp
+```
+
+Verify by asking gallery-dl's own interpreter, not the shell:
+
+```sh
+/home/matt/.local/share/pipx/venvs/gallery-dl/bin/python -c 'import yt_dlp'
+```
 
 ## Known quirks