Configuration helper: confusing wording for "directory for versioned Python commands"

[sparrowt]

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:

1. 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.

2. 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?

[sparrowt]

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:

C:\Users\tom.sparrow\AppData\Local\Python\bin

although the directory doesn't yet exist, presumably because I haven't used py-manager to install any python runtimes yet.

[sparrowt]

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?

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]

Yeah, some good points.

1. Which actual directory is this?

You found it, but printing it here isn't unreasonable. It is in fact the single directory that will be added to PATH and 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).

2. if I choose to add this to my PATH, why must I remove it later?

Because there's no uninstall process. We don't get to run commands when you uninstall the install manager.

However, py uninstall --purge will 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.

it didn't even offer to install a version of python for me which I'm fine with

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]

You found it, but printing it here isn't unreasonable.

It might also be useful to have it displayed via some pymanager command after the initial setup, so that someone (like me) who initially chose not to add it to PATH can 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 with pymanager list, but that's at least in part because there aren't that many subcommands to choose from. Maybe pymanager list --alias-dir?

[zooba]

It might also be useful to have it displayed via some pymanager command after the initial setup, so that someone (like me) who initially chose not to add it to PATH can add it later without needing to hunt in the docs for the right directory to add.

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):

Global shortcuts directory is not on PATH. Add it for easy access to global Python aliases.
Directory to add: C:\Users\<NAME>\AppData\Local\Python\bin

You can also py install --configure to re-run the configuration helper, which will let you just say "yes" and add it automatically.

[pfmoore]

Ah, I missed that. That seems like a reasonable solution 🙂

[sparrowt]

Thanks @zooba for each of your replies.

Re the last (most off-topic! sorry) bit:

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.

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:

• someone who has a previous version of python installed
• visits https://www.python.org/downloads/ looking for latest python; clicks prominent Download Python install manager button
• ends up finishing the first-run configure workflow but is then confused why it hasn't even offered to install latest python (or perhaps doesn't even realise that it hasn't installed one) seeing as they clicked the big button which was under the heading Download the latest version for Windows so 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:

It looks like you already have the following versions of python installed:
...
Python Install Manager is now installed - would you like to install the latest python (3.14.0)? [yN]

perhaps?

[zooba]

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:

• improved wording re: global shortcuts directory
• improved check for already having the latest runtime vs. any runtime at all