docs: Encourage `pipx` more strongly in installation guide
See original GitHub issueI love the new installation guide from @sbalnojan . However, one thing we lost in the transition to the new format was the prioritization of pipx
as the preferred installation method - and the instructions to leverage virtual environments if pip
is used directly.
-
I would suggest we change the order of the tabs from [1:
pip
, 2:docker
, 3:pipx
] to instead use: [1:pipx
, 2:pip
, 3:docker
]. People who want to do a ‘quick test’ and don’t want to install pipx can still just jump over to thepip
tab, and they can ignore the warnings/recommendations, but then if they do run into version conflicts, they remember ignoring the warnings and they know to come back and run it in one of the recommended methods. -
The
pipx
section links to thepipx
homepage, but it could also be helpful to link to the ‘how to install pipx’ content directly here: https://docs.meltano.com/guide/installation-guide#install-pipx -
The
pip
section also currently suggests a simple installation, which on its own is very likely to lead to version conflicts. I think we should definitely recommend virtual environments on thepip
tab, ideally with a warning about version conflicts, suggesting pip+virtualenv or pipx as the recommended path to avoid conflicts with other installed tools and libraries. To avoid blowing up the page withvirtualenv
explanation and instructions there on thepip
tab, I think we could just add something like this with links to content off the page:
Warning: We strongly recommend you use
pipx
for installation. If you choose to usepip
directly, we recommend creating a dedicated virtual environment to avoid conflicts with other installed software. Learn more here.
Issue Analytics
- State:
- Created a year ago
- Comments:6 (2 by maintainers)
Top GitHub Comments
@aaronsteers Ok there’s the rub. I was assuming a very different profile. Then we do need to change something, not sure yet how.
My gut feeling would be to then indeed push the pipx version, simply because teaching someone to handle venvs is hard, and would break the flow here. Better to use pipx then and simply “get it to work”, while also putting a clear disclaimer on top (“if you know how to handle venvs, just go ahead and do X; If not, here’s the easy way: …”).
That would still keep the discussion of venvs out of the quick install as well as most of the indepth install content.
@aaronsteers I think that makes sense. Sven was prioritizing speed of install generally, but if that comes at the expense of some downstream problems it may be worth taking a moment to recommend pipx. @sbalnojan thoughts?