Merge branch 'code/majorair/yt-dlp-update-docs'

05-troubleshooting/yt-dlp-fedora-js-challenge.md

@@ -10,7 +10,7 @@ tags:
   - deno
 status: published
 created: 2026-04-02
-updated: 2026-04-30T05:21
+updated: 2026-06-16T18:35
 ---
 # yt-dlp YouTube JS Challenge Fix (Fedora)
 
@@ -84,12 +84,43 @@ echo '--remote-components ejs:github' > ~/.config/yt-dlp/config
 
 ## Maintenance
 
-YouTube pushes extractor changes frequently. Keep yt-dlp current:
+YouTube pushes extractor changes frequently. Keep yt-dlp current.
+
+### Updating: the `-U` trap + avoid duplicate installs
+
+`yt-dlp -U` **does not work** when yt-dlp was installed via pip/PyPI — the PyPI build deliberately disables the self-updater:
+
+```
+ERROR: You installed yt-dlp with pip or using the wheel from PyPi; Use that to update
+```
+
+Update through pip instead. **Pick one install method and stick to it** — running both a user install and a system install leaves two copies that drift out of sync (one updates, the other stays stale and shadows it depending on `$PATH` / sudo).
+
+**Recommended — single user install (no sudo):**
+
+```bash
+pip3 install -U --user yt-dlp
+```
+
+This lives in `~/.local/bin/yt-dlp` and is first on a normal user's `$PATH`. Update it the same way; never use sudo.
+
+**Alternative — system-wide (Fedora, PEP 668):**
 
 ```bash
 sudo pip install -U yt-dlp --break-system-packages
 ```
 
+> Only use `--break-system-packages` if you intentionally want a root-owned copy in `/usr/local`. Do **not** mix it with a `--user` install.
+
+**Check for and remove a duplicate install:**
+
+```bash
+which -a yt-dlp            # more than one path = duplicate installs
+sudo pip3 uninstall -y yt-dlp   # removes the /usr/local (system) copy + its wrapper
+```
+
+> If installed via the standalone binary (not pip), `yt-dlp -U` is the correct updater.
+
 ---
 
 ## Known Limitations