673.changed.md

• The README now leads with pipx, and names PEP 668 by its error text (#673, closes #671). pip install soup-cli, the first command in the README, fails on Debian 12 and Ubuntu 23.04 or later:

  error: externally-managed-environment
  

  Those distros ship an EXTERNALLY-MANAGED marker in the system Python so pip refuses to write into a site-packages that apt also manages (PEP 668). It is the default on current Debian and Ubuntu, so it is now the ordinary first-run experience on Linux rather than an edge case, and nothing in Soup can rescue the command: the package is not installed yet when the README line runs.

  Soup declares a soup console script, which makes it an application rather than a library, so the install now leads with pipx install soup-cli and uv tool install soup-cli. Both give Soup its own virtualenv and put the command on PATH, which is outside PEP 668's scope entirely. Every existing pip install line is kept, under a sentence saying when it is the right choice: already inside a virtualenv, a Colab notebook, or a Docker image. A callout carries the literal externally-managed-environment string so the error text pasted into a search engine matches Soup's own README, and it also gives the python3 -m venv route for anyone who would rather not add a tool.

  Use pip rather than pipx if you want to import soup_cli alongside your own code; pipx isolation is the wrong shape for that.

  Documentation only. No packaging or command behaviour changed.