Repository navigation
Configuration helper: confusing wording for "directory for versioned Python commands" #187
Description
Background
Python Installation Manager installed from https://www.python.org/downloads/ onto a Windows 11 machine which has a bunch of existing MSI installed versions of python.
Details
A terminal window appears during installation and prompts me as follows:
********************************************************************************
The directory for versioned Python commands is not configured.
This will prevent commands like python3.14.exe working, but will not affect the
python or py commands (for example, py -V:3.14).
We can add the directory to PATH now, but you will need to restart your
terminal to see the change, and must manually edit environment variables to
later remove the entry.
Add commands directory to your PATH now? [y/N]
I'm pretty familiar with python and use it extensively but this wording left me confused in the following ways:
-
Which actual directory is this? Is this a version-agnostic directory managed by Python Installation Manager? Ideally it would print out the actual path - I like to know what is being added to my PATH.
-
I don't understand this bit at all:
and must manually edit environment variables to later remove the entry.
if I choose to add this to my PATH, why must I remove it later?
Activity
[-]Configuration helper does not explain "directory for versioned Python commands" well[/-][+]Configuration helper: confusing wording for "directory for versioned Python commands"[/+]sparrowt commentedon Oct 9, 2025
For the benefit of those wondering what it actually does... having begrudgingly said "y" without fully understanding the consequences, I found the following had been added to my user PATH:
although the directory doesn't yet exist, presumably because I haven't used py-manager to install any python runtimes yet.
sparrowt commentedon Oct 9, 2025
I now wonder if what it means is: "if you want to later remove this, you will need to manually edit your PATH environment variable" which would make sense - however I do think the current wording is pretty confusing.
Especially as the Python Installation Manager is intended to make things easier for new users (as a side observation, my experience so far with this auto-launched terminal window, is in fact much less user-friendly than the classic MSI installer - it didn't even offer to install a version of python for me which I'm fine with, but perhaps first-time users would expect? anyway this is off-topic...)
zooba commentedon Oct 9, 2025
Yeah, some good points.
You found it, but printing it here isn't unreasonable. It is in fact the single directory that will be added to
PATHand fully managed by the install manager, which seems like unnecessary explanation unless you've dealt with the past arrangement (multiple directories and managed by you).Because there's no uninstall process. We don't get to run commands when you uninstall the install manager.
However,
py uninstall --purgewill actually remove the path entry (as well as deleting any aliases in it, and any installed runtimes). It might be worth mentioning this here. Your point that the wording is confusing is well made.Because you already had one installed. If you didn't, it'd offer.
It's probably no surprise that there's 100% chance of someone complaining about every possible choice here - we had people complain about installing a new runtime when they already had one installed, which is why it currently won't install a runtime if it detects one.
pfmoore commentedon Oct 9, 2025
It might also be useful to have it displayed via some
pymanagercommand after the initial setup, so that someone (like me) who initially chose not to add it toPATHcan add it later without needing to hunt in the docs for the right directory to add. I'm not sure what the best subcommand would be - it feels like it fits best withpymanager list, but that's at least in part because there aren't that many subcommands to choose from. Maybepymanager list --alias-dir?zooba commentedon Oct 9, 2025
Like pip, we display the path on every install if you don't have it in PATH (including
py install --refresh, which just fixes up aliases without installing anything):You can also
py install --configureto re-run the configuration helper, which will let you just say "yes" and add it automatically.pfmoore commentedon Oct 9, 2025
Ah, I missed that. That seems like a reasonable solution 🙂
sparrowt commentedon Oct 10, 2025
Thanks @zooba for each of your replies.
Re the last (most off-topic! sorry) bit:
It's good to know that it would offer if I didn't have one already - I wouldn't expect it to automatically install one if I already had one, but I was a tad surprised when, after declining its offer to open the online help, the window just quit.
It sounds like it's more helpful for first timers (no existing install) which is good - however I think the following case is pretty common and could be improved:
Download Python install managerbuttonDownload the latest version for Windowsso it feels like it hasn't done what it said on the tin.Perhaps this should be split out to a separate ticket, but I think that case would cover a significant proportion of people - one possible improvement would be if the configure wizard had a final step which said something like:
perhaps?
zooba commentedon Oct 10, 2025
Yeah, updating the first-run check to look for at least the version that's bundled (which will usually be the latest stable) seems like a good tweak.
They're both related to first-run, so may as well stay here:
Improves message for global directory.
sparrowt commentedon Oct 14, 2025
Many thanks, the bits of #190 related to this ticket look good 👍
Improved first-run experience (#190)
garretwilson commentedon Aug 14, 2026
This is indeed confusing. So if
pythonandpyalready work without adding this to the path, why would I want to add this other directory to the path? Is it needed to runpipor something?Experts understand they need to add new programs to the path. They know that if the installer offers to add the program to the path for them, they should accept, because it's one less thing they need to do and, being automated, it's less error prone.
But if
pythonandpywould be available already, then why is this needed? Basically the "explanation" is saying, "you don't need to add Python to the path as you're accustomed to doing; but would you like to anyway, because you may need it, but we won't tell you why."zooba commentedon Aug 17, 2026
python3.14(for example) is only available if you add this path, as ispip/pip3.14/etc. and any other generated aliases for installed packages.But you're right, it's not necessary. If you only ever launch using
pyor an active virtual environment (as I personally do), then you don't need it. That's part of why it's optional. (The other parts are that we can't do it immediately on install, because it isn't supported by Windows, and because the terminal needs to be restarted and so the user needs to know it's just been done.)