Improve docs for resolving `space in home path` warning

[Gitznik]

How would this feature be useful?

The existing warning and docs are not enough for users to resolve it.

Describe the solution you'd like

Dedicated docs on how to move the home path and a clear link to it in the warning, as well as specifying it's the Pipx Home that has the space in it.

Describe alternatives you've considered

Hope people that are confused just find the existing discussions.

Discussed in https://github.com/pypa/pipx/discussions/1315

^{Originally posted by homocomputeris April 1, 2024} I get the message every time I run pipx.

• What is home path here?
• Where are the docs on this issue? Nothing can be found here: https://www.google.com/search?hl=en&q=%22home%20path%22%20site%3Ahttps%3A%2F%2Fpipx.pypa.io%2Flatest%2F
• How to fix or disable this warning?

[peeeeter]

Could you put a link to the most relevant discussion for mac os here? the only thing I found was to try "reinstall-all" but that didn't change the default bin path.

[scruffaluff]

I got the same message on MacOS everytime I used Pipx after the update to 1.5.0. The docs specify that if the folder ~/Library/Application Support/pipx exists, Pipx will prefer that folder over the default Pipx home of ~/.local/pipx. Since ~/Library/Application Support/pipx contains a space in its path, Pipx throws the space in the home path warning.

For me, running pipx uninstall-all, deleting ~/Library/Application Support/pipx, and then reinstalling my Pipx applications fixed the warning.

[Gitznik]

Thanks for providing that way of doing it @scruffaluff. That works perfectly fine if you're happy to reinstall all your pipx packages :)

The other option is described in this comment: https://github.com/pypa/pipx/discussions/1315#discussioncomment-9028696 This saves you from manually having to reinstall everything

[garthk]

I'd also:

• Amend the warning to say "PIPX_HOME" rather than "the home path"
• … and to suggest running pipx environment
• … and to add a link to the docs
• Tag the issues raised for the multiple incompatibilities
• Link to the issue search for that tag so the user has the detail necessary to assess their risk

This might strike some as a lot of fuss and bother, but I respectfully submit it's in proportion to the task you just set your users:

Found a space in the home path. We heavily discourage this, due to multiple incompatibilities. Please check our docs for more information on this, as well as some pointers on how to migrate to a different home path

@Gitznik, raising a doc-bug in response to the discussion was a good call. Onya.

[Gitznik]

Hi @garthk, Agreed to the first 3 points. Actually we should be able to create a full example of the script to run to move the pipx home right there in the warning, as we know the current and the preferred path. The user then just has to copy & paste (on mac and linux at least). A link to the docs further describing the process is a good idea as well.

For the last 2, I've opened a discussion that fully describes the reason and dangers of having a space in the path, so I think linking that/turning it into a part of the troubleshooting docs should be enough. It can be found here

Edit: Actually that discussion covers a lot more ground than just the spaces in the path, so I'll create a new one specifically for that, which can then be linked/turned into docs :+1:

Edit2: Created a discussion here: https://github.com/pypa/pipx/discussions/1330

[gingerbeardman]

Thanks @scruffaluff

No idea how ~/Library/Application Support/pipx was being used, i certainly didn't create it.

[albertpurnama]

Thanks @scruffaluff !

[gennaro-tedesco]

No idea how ~/Library/Application Support/pipx was being used, i certainly didn't create it.

Apparently ~/Library/Application Support is the default appdir on MacOs.

[gyoza]

It appears on MacOS pipx is ignoring the 'PIPX_HOME' environment variable?

# pipx environment
⚠️ Found a space in the home path. We heavily discourage this, due to multiple incompatibilities. Please check our docs for more information on this, as well
    as some pointers on how to migrate to a different home path.
Environment variables (set by user):

PIPX_HOME=/Users/me/Library/ApplicationSupport/pipx
PIPX_BIN_DIR=/Users/me/.local/bin
PIPX_MAN_DIR=/Users/me/.local/share/man
PIPX_SHARED_LIBS=/Users/me/Library/ApplicationSupport/pipx/shared
PIPX_DEFAULT_PYTHON=/opt/homebrew/opt/[email protected]/libexec/bin/python
PIPX_FETCH_MISSING_PYTHON=
USE_EMOJI=

Derived values (computed by pipx):

PIPX_HOME=/Users/me/Library/Application Support/pipx

Using pipx 1.6.0 installed via brew.

[Gitznik]

It appears on MacOS pipx is ignoring the 'PIPX_HOME' environment variable?

# pipx environment

⚠️ Found a space in the home path. We heavily discourage this, due to multiple incompatibilities. Please check our docs for more information on this, as well

    as some pointers on how to migrate to a different home path.

Environment variables (set by user):



PIPX_HOME=/Users/me/Library/ApplicationSupport/pipx

PIPX_BIN_DIR=/Users/me/.local/bin

PIPX_MAN_DIR=/Users/me/.local/share/man

PIPX_SHARED_LIBS=/Users/me/Library/ApplicationSupport/pipx/shared

PIPX_DEFAULT_PYTHON=/opt/homebrew/opt/[email protected]/libexec/bin/python

PIPX_FETCH_MISSING_PYTHON=

USE_EMOJI=



Derived values (computed by pipx):



PIPX_HOME=/Users/me/Library/Application Support/pipx

Using pipx 1.6.0 installed via brew.

I assume you symlinked Application Support to ApplicationSupport? We resolve all symbolic links when defining the paths, hence the behavior you see.