Opened 4 months ago

Closed 3 months ago

Last modified 3 months ago

#35511 closed Cleanup/optimization (fixed)

Documentation uses the py binary in Windows, which may not always be available

Reported by: Alex Owned by: Alex
Component: Documentation Version: dev
Severity: Normal Keywords: windows
Cc: Alex, Baptiste Mispelon Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

In places like the tutorial, the windows version of the command always uses py like, py -m django --version.

The py binary is available only if python is installed via the python.org installer. However, if you install python via the Microsoft Store, the pybinary is not available.

When you install Python from the Microsoft Store, the py command is not included. For Linux, macOS, WSL and the Microsoft Store version of Python, you should use the python3 (or python3.7) command.

https://learn.microsoft.com/en-us/windows/python/faqs#what-is-py-exe-

The python.org installer adds py by default, however, it only adds python if the option "Add python.exe to PATH" is selected in the first step of the installer.
Without the option, typing python or python3 will launch the Microsoft Store

I would recommend that in the install section have specific instructions for Windows to use the python.org installer, not the Microsoft Store one. Also explain that the store one, doesn't have py.

Change History (10)

comment:1 by Sarah Boyce, 4 months ago

Triage Stage: UnreviewedAccepted

I think having a note in the how to install for Windows section might be more appropriate.
I think the note can be that py may need to be python or python3 depending on how they installed Python 🤔

Happy to see a PR 👍

comment:2 by Sarah Boyce, 4 months ago

Cc: Baptiste Mispelon added

in reply to:  1 comment:3 by Alex, 4 months ago

Replying to Sarah Boyce:

I think having a note in the how to install for Windows section might be more appropriate.

I was unaware of this page, and I think that's a problem. The how to page seems like a catch all for guides, but I doubt most people using windows that follow the tutorial will find it.

To find it, if you start at the install page of the tutorial, you have to first click in complete installation guide and then on How to install Django on Windows.

The quick install guide, which says "this guide will guide you to a minimal installation that’ll work while you walk through the introduction.", has no direct mention of Windows, of the binary differences.

So while the note in the Windows page would be needed, I think the the install page should either link very clearly to the windows instructions or have the same or a similar note to the one that needs to be added in the Windows page. I'm not sure which of these two options would be better.

comment:4 by Sarah Boyce, 4 months ago

So on the install page you linked (which is the quick install intro), in the first paragraph there is a link to the complete installation guide. On that page, in the first section there is a link to the Windows installation guide. This is quite logical to me considering we are talking about specific cases and trouble shooting.
To me, the quick guide should be "quick/light" and not bombard the user with too much information. They should refer to the complete guide if they encounter issues

comment:5 by Alex, 4 months ago

Has patch: set

comment:6 by Sarah Boyce, 4 months ago

Patch needs improvement: set

comment:7 by Alex, 3 months ago

Patch needs improvement: unset

comment:8 by Sarah Boyce, 3 months ago

Triage Stage: AcceptedReady for checkin

comment:9 by Sarah Boyce <42296566+sarahboyce@…>, 3 months ago

Resolution: fixed
Status: assignedclosed

In 2e47dde4:

Fixed #35511 -- Documented when the py binary is unavailable on Windows.

comment:10 by Sarah Boyce <42296566+sarahboyce@…>, 3 months ago

In c4d3434:

[5.1.x] Fixed #35511 -- Documented when the py binary is unavailable on Windows.

Backport of 2e47dde438d689199934bca0967152a3b0e8a95f from main.

Note: See TracTickets for help on using tickets.
Back to Top