[UX] Clarification: 'pipx' command not found - Installation required in Windows OS

[sn3hay]

Description Reference: https://www.pyopensci.org/python-package-guide/tutorials/get-to-know-hatch.html When trying to run: pipx install hatch in Windows command line, the following error is faced: 'pipx' is not recognized as an internal or external command, operable program, or batch file.

Steps to Reproduce

1. Open a terminal or command prompt.
2. Try running pipx install hatch

Expected Behavior The pipx command should be recognized and install the package in an isolated environment.

Actual Behavior The error message "pipx is not recognized" appears as an internal or external command, operable program or batch file.

Solution Install pipx using pip install pipx.

• pip install pipx

This is not a bug report but rather a clarification to help users understand the issue.

[pb-413]

Great information!

The first mention of pipx is a link to their page. That page includes a section "On Windows," which recommends scoop (I'm not familiar with that) or pip. The pip steps from there:

1. py -m pip install --user pipx
2. navigate to install directory
3. .\pipx.exe ensurepath

Perhaps it would be valuable to elaborate on the recommended actions and tools here like you say, or we can expect the audience to go through the link and get the recommended tool using the right steps for their machine.

When I went through this step, I decided to use the discouraged approach of installing hatch via pip because I felt comfortable making sure that I installed it outside any virtual environments.

[zackw]

Hmm, I think the key issue here is that a naive reader may not realize that pipx itself may need to be installed, even if you've already installed Python. We can refer to the pipx documentation for how to do that, but we should make clear that it doesn't come with the OS or with core Python.

[pb-413]

Sounds good @zackw; I could agree with that!

[sn3hay]

Agreed! Adding something as simple as a sidenote should help.

[pb-413]

After our discussion IRL, I was curious how hatch itself recommends installing on Windows. Here is that: https://hatch.pypa.io/dev/install/#windows

Have not tested that, but seems to rely on native tools rather than grabbing something else; that seemed to be our aim?

1. msiexec /passive /i https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi
2. Restart your terminal.
3. hatch --version to verify installation

hatch also mentions that it can be installed via pip, but warns that you might want to use pipx, 😅

I'm unfamiliar with the problem pipx is trying to solve, so I defer to those with more experience with such tools.

[Vaunty]

This is a walkthrough of all the steps I made, as a Windows user, to install Hatch. I hope to limit the amount of windows users facing issues with installation, as the first step is impossible (at least for me) without these steps.

Step 1: Open Powershell

Step 2: Check to see if python is installed Copy and Paste python --version If Python is not installed, don't be alarmed!

Step 2.5: Download python from https://www.python.org/downloads/

Step 3: Using "curl" (a curl is a tool for transferring data requests to and from a server) you can download Pip Copy and Paste: curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py Copy and Paste: python get-pip.py

Step 4: Download Scoop Copy and Paste: iwr -useb get.scoop.sh | iex If any errors try Copy and Paste: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser Then retry Copy and Paste: iwr -useb get.scoop.sh | iex

Step 5: Install Pipx Copy and Paste: scoop install pipx Copy and Paste: pipx ensurepath

After completion of Step 5, the "Get to know hatch" Tutorial can be followed to completion without any more issues (atleast for me). Meaning you can actually do the first step for the tutorial " pipx install hatch " .

[willingc]

Related to #270. Let's incorporate Ofek's suggestion from that issue.

Next action: https://github.com/pyOpenSci/python-package-guide/issues/270#issuecomment-2138319940

[lwasser]

@willingc would that be using the hatch installers rather than a different way to install on windows vs mac? i believe we have an open pr with instructions that @vaunty created. i'm not sure how to best navigate this but i DO know that our windows users had a lot of installation issues - most of which were related to pipx on windows (so allowing for a global hatch install on windows was hard)

[lwasser]

does anyone here use windows? if we can get a confirmation that the windows installers work then i vote that we

1. remove pipx altogether - eeks!
2. tell people to use the hatch installers

this i think would be the simplest path for users IF the windows installer is straight forward to install. pipx seems to NOT be straight forward to install across operating systems so let's avoid it.

we just needs a windows user to test this - i don't have windows unfortunately.

[pb-413]

I have windows and can capture steps using the installer mentioned in the other issue!

[lwasser]

that would be awesome!! a pr is also welcome if you have bandwidth. and if not, i can tag this as help-wanted and we will have windows details that you provide here! thank you so much! this is going to improve things a lot.

[kierisi]

here are the steps I used on Windows (with the caveat that I don't do any Python work on my Windows machine, so this is all from a very naive-to-coding-on-Windows perspective):

• I followed the Windows GUI instructions on the Installation - Hatch page, downloading the recommended hatch-x64.msi file. when I tried to run it, I immediately got a security pop-up saying that running the app would put my PC at risk. clicking "More Info" expands the options to get to the "Run Anyway" button.
• I then got a Setup Wizard window and ran it with all of the defaults. if it looks like the installation is stalled, check to ensure there isn't an additional Windows security notification that needs to be cleared (mine only appeared in the menu bar, instead of as a pop-up).
• in the terminal I ran hatch --version, which returned Hatch, version 1.12.0

everything worked as expected, and the biggest issues were related to bypassing Windows security warnings.

[lwasser]

Wow well that is WAY simpler @kierisi than all of the pipx instructions that others were using. Thank you!!

Windows & security

That security item - that is likely a standard windows challenge. Does anyone here know by chance if we can with confidence just tell users that they can always trust hatch installers? would that pop up for any installer that wasn't "windows certified?" so i wonder if that pops up when you install anaconda for instance. thank you all.

it sounds like we have a path forward here that will work much better than our current lessons do!

[pb-413]

would that pop up for any installer that wasn't "windows certified?"

Having to confirm that installers are making changes to your machine is pretty standard when you install software on Windows.

As long as we are linking to a trusted source for the installer, instructing a user to confirm that prompt is probably expected.

[lwasser]

ok fantastic. y'all - i've just opened this pr which updates the installation instructions

A few things we learned chatting in #301

1. the installers seem to be the way to go for windows and MAC (altho mac also supports homebrew install which people might have and prefer)
2. Hatch installs Python for you using UV if you don't have Python! so the installers provide an additional win of Python!

Reviews are welcome on my open PR!! we are teaching a workshop the week after next so i'll leave this open for a week with the plan to merge next tuesday July 2! this issue can then be closed! 🚀