Add guide for working with Python on Windows #773
Conversation
✅ Deploy Preview for pydis-static ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
wookie184
force-pushed
the
add-windows-guide
branch
from
0129205
to
2781ed9
Compare
|
This still isn't quite finished, but it'd be good to get some reviews on the content. Please leave a comment if you think there's anything that should be added (you can take a look at the linked issues for ideas). |
|
Thanks for this! A few immediate comments:
|
Yeah, that would probably make sense
WDYM by "py installer"?
I mention that here https://deploy-preview-773--pydis-static.netlify.app/pages/guides/python-guides/python-on-windows/#the-advanced-method-editing-environment-variables, although maybe it should be moved to another point on that page or made more obvious?
|
Oh sorry I meant the microsoft store page.
Ah I missed that. yeah maybe it should be in the form of "this is what you need to make sure of to make it work". EDIT: Also I would expect it to be in the section below where the instructions for adding to PATH are. |
Well, I don't think we should recommend that people use it (due to said caveats), so i'm not sure what else would be on such a page (maybe how to uninstall it lol).
👍 |
wookie184
added
type: feature
Xithrius
requested review from
AbooMinister25,
Bluenix2,
eivl,
Xithrius and
fisher60
…lanned changes and have nice order
…/installing-and-using-python.md Co-authored-by: wookie184 <[email protected]>
…/installing-and-using-python.md Co-authored-by: wookie184 <[email protected]>
…/installing-and-using-python.md Co-authored-by: wookie184 <[email protected]>
…/common-issues.md Co-authored-by: wookie184 <[email protected]>
…/installing-and-using-python.md Co-authored-by: wookie184 <[email protected]>
…/putting-python-on-path.md Co-authored-by: wookie184 <[email protected]>
…/putting-python-on-path.md Co-authored-by: wookie184 <[email protected]>
…/putting-python-on-path.md Co-authored-by: wookie184 <[email protected]>
…python-discord-site into add-windows-guide
|
I think python-discord/bot#794 now has all the content of your PR combined there, isn't it ? Should we just keep one PR then ? |
I'm for that. I think python-discord/bot#794 is ready to be merged into here (or however that works exactly) if wookie signs off on it. The "TODO: Add more screenshots" is done, and python-discord/bot#794 has articles that could be linked from most of the proposed !install, !windows-path, etc. tags (to supplement, not replace the tags). |
Proofread, reorganized, and added to all the "Python on Windows" guides
| ### When I run `python` in the terminal I get no result, or the Microsoft Store opens! | ||
|
|
||
| By default Windows has an alias for `python` in the terminal to guide you to install it from the [Microsoft | ||
| Store](https://apps.microsoft.com/store/search/python). We don't recommend installing Python from the Microsoft | ||
| Store, see why [here](../microsoft-store). To disable this alias, search "App execution aliases" in Windows search | ||
| and click on "Manage app execution aliases". In the list you should see two options with title "App Installer" and | ||
| descriptions `python.exe` and `python3.exe`. Disable both of them. | ||
|
|
||
| Note that if you are following instructions telling you to run a command starting with `python3`, those instructions are | ||
| intended for Unix/macOS systems. Try just using `python` instead. | ||
|
|
||
| If after doing this you have an issue with the Python command not being detected, see the question below. | ||
|
|
||
| ### When I try and run my code with `python` in the terminal I get an error saying the command was not recognized | ||
|
|
||
| If you have not installed Python, you will need to do that. Follow our guide [here](../installing-and-using-python). | ||
|
|
||
| If you have installed python and are still having the issue, it is likely that you didn't check the "Add python.exe to | ||
| PATH" checkbox on the first page of the installer. See [our guide on adding Python to PATH](../putting-python-on-path) | ||
| for how to fix this. You can also use the `py` launcher instead of `python` by just replacing `python` in your command | ||
| with `py`. See [this guide](../installing-and-using-python/#the-py-launcher) for more information on that. |
There was a problem hiding this comment.
I would say that using the py launcher should be the first recommendation. Managing the aliases isn't necessary if you stick with using it. I'd say change the section a little where using py is the default recommendation, and another header saying "If you still want to using python instead of py
There was a problem hiding this comment.
We should probably also address here or below how to install using py by doing py -m pip install [package_name_here].
| for how to fix this. You can also use the `py` launcher instead of `python` by just replacing `python` in your command | ||
| with `py`. See [this guide](../installing-and-using-python/#the-py-launcher) for more information on that. | ||
|
|
||
| ### I `pip` installed a package but when running my code I get a `ModuleNotFoundError` |
There was a problem hiding this comment.
As above, the usage of py -m pip install can be both helpful and important. If there is an issue with the PATH or other factors, python and pip may point to different versions. Using py -m pip install guarantees that whatever you pip install will go into that py version.
| > `pip install` command in the VSCode terminal should work. If you are not using a virtual environment, you can use | ||
| > the `py` launcher to specify the installation you want to install to. | ||
|
|
||
| ### I `pip` installed a command line program but it isn't recognized |
There was a problem hiding this comment.
Again, py launcher can help rectify some of this, including running some even when \Scripts isn't in the path. For example if you py -m pip install black, then try to just do black it may not work. But if you do py -m black it should.
There was a problem hiding this comment.
This works well for some tools, but not others. For example, with pyinstaller you have to run py -m PyInstaller with that exact capitalisation - something that I don't believe is clearly documented anywhere, the docs just say to use pyinstaller directly so it's confusing when that doesn't work. There are also other tools that don't have any -m alternative that i've been able to find, like https://csvkit.readthedocs.io/en/latest/.
The py installer is nice, but it requires a certain amount of knowledge to know when and how to convert commands given in documentation to work with py. I think users generally want to be able to run commands in the way that docs give them.
It's annoying that stuff like this is such a minefield, there are a bunch of ways to make things work using just the py launcher - like by using pipx for tools and virtual environments when you want to just be able to python, but I wanted to try and keep this guide fairly simple.
|
|
||
| ### I get a `SyntaxError` when trying to run `pip`,`python`, or another command. | ||
|
|
||
| When you type `python` in the terminal you enter into the python REPL ([read-evaluate-print |
There was a problem hiding this comment.
| When you type `python` in the terminal you enter into the python REPL ([read-evaluate-print | |
| When you type `python` or `py` in the terminal you enter into the python REPL ([read-evaluate-print |
| you run `Python` code line by line without having to create a file. You also may have opened a Python REPL by clicking | ||
| on the Python App in your Start Menu. | ||
|
|
||
| General commands like `pip` and `python` should be run in your computer's normal terminal, that is, directly in |
There was a problem hiding this comment.
| General commands like `pip` and `python` should be run in your computer's normal terminal, that is, directly in | |
| General commands like `py`, `pip` and `python` should be run in your computer's normal terminal, that is, directly in |
|
|
||
| Our recommended way of installing Python on a Windows operating system is using the full installer from the official | ||
| [python.org Downloads page](https://www.python.org/downloads/) (from the big yellow button) using the default options, | ||
| except making sure to check the "Add python.exe to PATH" checkbox. Getting Python from the [Microsoft |
There was a problem hiding this comment.
I would highly recommend NOT adding python to PATH. The py launcher handles most if not all of that pathing. This will also prevent potential issues if you have multiple different versions of Python installed on your machine.
| 3. Check the "Add python.exe to PATH" checkbox (the text may differ slightly depending on your installer). This will | ||
| make it so terminals can recognize commands like `python` and `pip`. (Read [this | ||
| guide](../putting-python-on-path) to learn more.) |
There was a problem hiding this comment.
As above, I recommend not adding to PATH.
|
|
||
| [](/static/images/content/python-on-windows/recommended_install_7.png) | ||
|
|
||
| Or try the more usual way of running Python by typing `python` in a new terminal window to open up the Python |
There was a problem hiding this comment.
| Or try the more usual way of running Python by typing `python` in a new terminal window to open up the Python | |
| Or try the more usual way of running Python by typing `py` or `python` in a new terminal window to open up the Python |
| [Here's a VSCode tutorial](https://code.visualstudio.com/docs/python/environments) and [here's | ||
| one for Pycharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html). | ||
|
|
||
| The `venv` module used above comes with Python, but [Poetry](https://python-poetry.org/), |
There was a problem hiding this comment.
Possibly add pdm to the list as that one has been growing in popularity. https://pdm.fming.dev/
| @@ -0,0 +1,254 @@ | |||
| --- | |||
There was a problem hiding this comment.
I would add a huge caveat about this section. Adding to PATH is not necessary when using the py launcher, and really shouldn't need to be done unless you just want to or you have a particular reason.
|
Hi everyone, is there a way to help out with getting this pull request merged? |
|
Hi @wookie184. Did you find some time to look at the review comments, or is this up for grabs? |
hedyhli
added
s: waiting for author
|
If we can make a decision on whether to guide the user to have I prefer getting the user to have |
wookie184
added
status: planning
I can't really comment on this as I do not run Python on Windows but your reasoning makes sense to me, and we should leave it mostly as is. |
This is intended as a step towards closing these issues:
After this we may want to add some summary tags linking to individual parts/pages here.
Pages on the preview:
https://deploy-preview-773--pydis-static.netlify.app/pages/guides/python-guides/windows/