Why does Pip documentation refer Windows to use an executable named "py"?

[notatallshaw]

Description

I'm trying to follow user guides on getting pip development done and one of the things I notice is that it refers to executing python through an executable called py.

I run Python almost exclusively on Windows and I don't know what py is, I can't google it because "py" or "python py" or "py executable" are all too generic for Google so I can't find any documentation on it, instead Google thinks I'm talking about the ".py" extension.

I think it's something that ships optionally with the Python installer from the Python Foundation? But if so it's optional as I've never had it installed. But even so I don't think it ships with the Python from the Windows store, or the Python in Anaconda, Miniconda, Miniforge, Mambaforge, etc...

So why is pip referring to py which is this optional thing that's impossible to find documentation on rather than just python which is what works on both Windows and other platforms?

Expected behavior

python

pip version

all

Python version

all

OS

Windows

How to Reproduce

Read Documentation

Output

No response

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[pfmoore]

py is the Python launcher, and it's covered in the documentation.

It's the recommended way of running Python on Windows, not just by pip, but in general, precisely because the python command does not work consistently (it's not installed on PATH by default in the python.org installers, it doesn't behave the same as on Unix, where python runs Python2, and you need python3 to run Python 3, etc).

The pip documentation is written for users of "standard" Python, so what Anaconda does is not really relevant (apart from anything else, if you're using Anaconda you should be using conda, not pip, anyway). The Windows Store Python is an oddball, which doesn't work the "standard" way. I don't know why they chose to work differently, but frankly it's just made things more complicated than they already were 🙁

Basically the answer is "it's all a complicated mess, and nothing works properly across all possible distributions/environments". The most likely thing to work by far on Windows has always been py, so that's what we document.

If someone wants to improve the documentation to explain all of this complexity, then I'd be fine with someone having a go. But you should look at the history fist - this has all been thrashed out many times in the past. Circumstances do change, so that's not saying we won't change the docs, but in my personal opinion, things haven't changed enough yet to make that worthwhile.

[notatallshaw]

py is the Python launcher, and it's covered in the documentation.

Thanks for the docs. I uninstalled all versions of Python on my computer and ran the Python Foundation installer and it does indeed default to "Install Launcher for all Users (recommended)". I guess crappy Windows installers have taught me to untick all options that say they are going to install something that isn't the exact thing I am wanting to install.

It's the recommended way of running Python on Windows, not just by pip, but in general, precisely because the python command does not work consistently (it's not installed on PATH by default in the python.org installers, it doesn't behave the same as on Unix, where python runs Python2, and you need python3 to run Python 3, etc).

Unfortunately py does not work consistently either it seems, with either the Windows Store package or conda based installers 😞

apart from anything else, if you're using Anaconda you should be using conda, not pip, anyway

Conda is multi-functional, it's not just a pip replacement. A perfectly valid use case is to manage the binary dependencies in your enivonrment with conda such as Python, NodeJS, OpenSSL, Rust Compiler, etc. and then use pip to manage your python packages. For a number of reasons this is one of the way I advise teams develop Python applications inside the company I work at.

The Windows Store Python is an oddball, which doesn't work the "standard" way. I don't know why they chose to work differently, but frankly it's just made things more complicated than they already were 🙁

I wonder if we can ask @zooba on this?

Basically the answer is "it's all a complicated mess, and nothing works properly across all possible distributions/environments". The most likely thing to work by far on Windows has always been py, so that's what we document.

If someone wants to improve the documentation to explain all of this complexity, then I'd be fine with someone having a go. But you should look at the history fist - this has all been thrashed out many times in the past. Circumstances do change, so that's not saying we won't change the docs, but in my personal opinion, things haven't changed enough yet to make that worthwhile.

Fair enough, I guess to start off with it might be nice to have the above link in pips docs. First I will try and get pip's development environment working on my machine and build up some experience with py and any other tools.

[zooba]

The Windows Store Python is different because it can't manage the py.exe installed by the traditional installer. So it was going to make things even messier if it tried to install it into a different location that may/may not be overruled by a traditional install, and all it would have the ability to do is to launch the Python that it was installed with.

The best way to launch pip if you've installed from the store is pip3.10 (or whatever your version is). It's not the usual launcher, and so none of the issues associated with a regular pip install ... apply. If you manage the execution aliases carefully, for which there is standard Windows UI (though it's not very good...), you can confidently use pip3 or just pip as well (and python3.x, python3 and python also work).

In most cases it's expected to be an alternative to the traditional install. If you get it from the Store, you wouldn't install it from python.org as well (and I certainly haven't installed from python.org since 3.8, because I've got the Store install around).

So given that it wasn't going to be reliably consistent with the past Windows experience, that the past Windows experience was woefully inconsistent with everyone's POSIX-by-default instructions, and we didn't have PATH concerns, we went with a more POSIX-like design. (I'm sure I've had this conversation before on this tracker, but guess it didn't turn into doc updates...)

[pfmoore]

I'm sure I've had this conversation before on this tracker, but guess it didn't turn into doc updates...

If you've any suggestions for how the docs can cover this without being even more confusing than they already are, PRs would be appreciated 😉 Personally, I find the inconsistencies that Store python introduced sufficiently annoying¹ (in terms of "it was hard enough to explain before, this just made it worse") that I'm unlikely to tackle such a change myself.

¹ I understand that Store apps have constraints that mean they can't work like the python.org installers, and I have no doubt that the Store install is the most sensible design it can be given those constraints. And maybe even better overall, if we ignore compatibility as a constraint. But it still annoys me that Store python has to be an exception to the "classic" behaviour on Windows.

[notatallshaw]

The best way to launch pip if you've installed from the store is pip3.10 (or whatever your version is). It's not the usual launcher, and so none of the issues associated with a regular pip install ... apply. If you manage the execution aliases carefully, for which there is standard Windows UI (though it's not very good...), you can confidently use pip3 or just pip as well (and python3.x, python3 and python also work).

This information is very useful thanks, I will try to propagate it further when I update the Python guides for my company or answer Python questions in Reddit.

I'm sure I've had this conversation before on this tracker, but guess it didn't turn into doc updates...

If you've any suggestions for how the docs can cover this without being even more confusing than they already are, PRs would be appreciated 😉

I can't speak for others but I know I don't have a suggestion right now, I will continue to think on it. But if you want to close this issue feel free to, can always open another or a PR if I feel convinced of a better solution.

[pradyunsg]

Well, given that I've been fiddling with the docs a whole lot lately, I'd be happy to pick up the documentation updates and make the PR necessary for it here; if someone could state more clearly what the changes need to be.

It sounds like we have a more Unix-y experience with the Windows store Python?

[pfmoore]

My main concern is that I suspect that many of the people who get confused over this sort of question may be equally confused if you ask them "are you using Python from the Windows Store or from the official installers?" (To say nothing of Anaconda, Chocolatey, cygwin, mingw64, or the various other places they could have got Python from). So before we branch off into whether to use py or python, we need to answer that question, otherwise we'll not actually be helping much...

[pradyunsg]

All of this is making me think that we should add a paragraph/section/page, talking about "how to run pip" somewhere; to discuss these nuances -- and use exactly one format in the rest of pip's documentation.

[uranusjr]

This is not really a pip issue, but I'm wondering if Windows Store apps allow for requesting dependencies. If it's somewhat possible, I'd rather much prefer CPython to officially distribute py in the Store that gets installed when any Python version is installed. The py command made calling Python on Windows much easier for newcomers, and it's very disappointing that CPython is now effectively breaking their own good idea and actively confusing everyone.

[pfmoore]

To be honest, I think that it would be better if we could simply link to a central document that says "how to run Python" and then say for pip you run python -m pip where people should read "python" as meaning "whatever incantation you need to run Python (see the linked document)". Unfortunately I don't think there is such a document.

The lack of clear, beginner-friendly instructions on how to run Python (in a way that allows you to add command line arguments like -m pip) is not pip's issue, but it does cause problems for us (and other projects).