I have updated the “How to” Guide for Installing Packages with pip and venv. Update how to guide to install using pip and venv by willingc · Pull Request #1338 · pypa/packaging.python.org · GitHub
I have done my best to apply the principles of diataxis for how to guides (About how-to guides - Diátaxis) as summarized here:
- focused on tasks or problems
- assume the user knows what they want to achieve
- action and only action
- no digression, explanation, teaching
I also approached the edit with the following in mind:
- Remove dated material
- Improve user experience
- Keep focused on the task and minimal explanation (explanation is better suited for a tutorial or a explanation/discussion document)
Thank you very much for the update! I’m very pleased to see the documentation improvements over the past few weeks
I do however have one very strong objection which is that I think we should promote
virtualenv more prominently or perhaps use that exclusively, which is the reverse of your current PR. It is orders of magnitude faster, allows for bug fixes outside of Python’s release cycle, and has far more features like activation scripts for newer shells.
Hatch and other tools that manage environments like tox simply cannot use the standard library version. I don’t mean this in any way to disparage maintainers of the standard library module but I seriously think we should consider getting rid of it.
I disagree strongly with this. Being able to create virtual environments without needing a 3rd party library is important. And
venv itself is extremely fast, what’s slow is installing pip into the environment.
virtualenv addresses this by caching pip locally and symlinking, but a much simpler solution these days is simply not to install pip (and use an external pip’s
--python argument). It’s not always a good solution, but it’s certainly workable (pipx uses something similar, just using some hacks to work around the fact that older pips didn’t have
--python, and it’s worked well).
I haven’t looked at the PR yet, so I can’t comment on whether using
venv is the right choice for this document, but IMO the stdlib venv is absolutely a reasonable tool to use if it’s appropriate for your use case.
I don’t mean this in any way to disparage maintainers of the
standard library module but I seriously think we should consider
getting rid of it.
Out of curiosity, how would I pip install virtualenv (or anything
else) into a virtual environment without already having an installed
tool capable of creating a virtual environment? Does virtualenv come
with a self-bootstrapping cross-platform installer now? This was a
major pain point in the bygone era before CPython began to include
venv. Now I use venv for almost everything I previously relied on
virtualenv for anyway, not only solving the bootstrapping problem
but also being just one less thing I (or my users or contributors on
my projects) have to install to get things going.
Thanks for the appreciation.
Here’s my current approach and the rationale for it. Initially, I am focusing on “How to” guides (see https://diataxis.fr/) first. Since a “How to” guide is a specific task oriented doc to perform a task (in this example Installing packages in a virtual environment using pip and venv). I could see there being a separate “How to” guide about Installing packages in a virtual environment using pip and virtualenv (or some other combination).
I’m trying to stick to a specific task per “How to” guide. I want to update information but I believe that a reasonable path to make progress on the docs is to present accurate information first. I’m not looking to make the recommendation now of which approach or tool is best. There’s not consensus on recommendations. So, I’m taking the approach of give accurate info first and build recommendations over time and placing them in the Tutorial or Overview to Packaging sections.
It’s fascinating how hard it is to stick to this principle (I constantly find myself adding little explanations and asides - just like this one ). Engineering types want to be complete, but that may not make a readable document - one of the Diátaxis benefits is the recognition of this fact. Keep it up!
Both pip and virtualenv are available as standalone
.pyz files, which can be run using any Python interpreter. For pip, it’s not the standard approach, but it’s supported and effective. For virtualenv it’s the recommended way of using it, I believe.
That’s the opposite model of what I am used to and what I’ve seen others do in practice. Rather than creating a virtual environment to install a better virtual environment creator, pip is usually installed in the base environment and you would install virtualenv that way.
I view ensurepip (in the cases where pip is not installed by default for some reason) as removing the need for the standard library module.
That’s the opposite model of what I am used to and what I’ve seen
others do in practice. Rather than creating a virtual environment
to install a better virtual environment creator, pip is usually
installed in the base environment and you would install virtualenv
GNU/Linux distributions are increasingly disallowing
sudo pip install ... and
pip install --user ... expecting virtual
environments to be used instead. Granted, they also typically offer
an installable python3-virtualenv package so that could be used to
get around the bootstrapping problem by using their (older)
virtualenv to create an environment and then install a new version
of virtualenv into it for subsequent invocations.
The earlier recommendation of running virtualenv’s zipapp instead of
installing it makes some sense too. The last time I had looked into
it, there was no zipapp for virtualenv, so that’s a cool