[docs] Don't recommend installing with pip install -U?

[baggiponte]

Hi there!

This is a bit nitpicky, but I would like to ask whether you would consider an update to your installation docs. While pip install --user is handy and immediate, it does not ensure isolation of the dependents. In other words, installation might fail if the user has a bunch of libraries installed this way; and by the way pip uninstall --user pathway only removes pathway and not the direct dependencies (sqlglot, etc).

The recommended way would be to point the user to using a virtual env:

python -m venv -- .venv
python -m pip install pathways

Or, if they wish to use pathways across multiple environments, the semi-recommended approach is to use pipx, or uv which does this amongst other things (it's basically cargo for Python).

What do you think? I'd be glad to submit a PR.

[embe-pw]

I don't think we recommend using --user anywhere? Note that for -U in pip install is short for --upgrade, not --user.

I agree that using a separate environment (or even better some tool like poetry or uv) is probably best, but it seems to be a bit outside of the scope of our installation instructions. Maybe we could a note that installing in a separate environment is preferred? Do you have any suggestions of some documentation we could link to?

Additionally, not sure about uv, but AFAIK pipx does not allow installing libraries, only binaries (making the library globally available would not be too different from what pip install --user does with all its downsides...)

[baggiponte]

Ops totally my bad! 😅

I agree that using a separate environment (or even better some tool like poetry or uv) is probably best, but it seems to be a bit outside of the scope of our installation instructions. Maybe we could a note that installing in a separate environment is preferred? Do you have any suggestions of some documentation we could link to?

Makes sense. As for the documentation: I was surprised by how little official documentation I could find clearly stating that "you must use a venv to develop software, otherwise there be dragons". Two refs:

1. https://docs.python.org/3/library/venv.html
2. https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments

I found a couple of things from the vscode docs but they also mention conda and I think it might generate more confusion than not. Oddly enough, there's an old reference from Princeton that mentions everything; though it mentions Python 3.7 since it dates back to 2015.