diff --git a/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md b/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md deleted file mode 100644 index 635c384f0..000000000 --- a/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Creating a Unix-style Python Environment on Windows -description: How to setup Python for Windows. ---- - -Many programmers use Linux or macOS operating systems for their work, though newcomers to programming will likely want to get started on the computer they already own, which will often be running Windows. -This guide will help you install Python on Windows. - -Programmers also need to become comfortable using a command prompt (also known as a terminal), and many guides for both beginning and advanced programming will often tell you certain commands to run. -The Windows command prompt has different names for similar commands that are available on Linux and macOS. -This guide will also help you set up a command prompt called Git Bash, which will support many of the commands available on Linux and macOS. - -## Installing Python -Python can be downloaded from the Python website on the [downloads page](https://www.python.org/downloads/). -The website will automatically present you with a download button for the latest release of the Windows version when you access the site from a Windows machine. - -Once the download is complete, you can begin the installation. -Select "Customize Installation". -The default settings for "Optional Features" are sufficient and you can click "Next". - -The next step is to decide on a location where the Python executable can be stored on your computer. -This should be a location that's easy for you to remember. -One possibility is to create a folder called "Python" at the root of your hard drive. -Once you have selected a location, you can click "Install", as no other settings on this screen need to be adjusted. -This will complete the installation. - -## Installing a text editor -You will also need a text editor for writing Python programs, and for subsequent steps of this guide. -Powerful programs called integrated development environments (IDEs) like PyCharm and Visual Studio Code contain text editors, but they also contain many other features with uses that aren't immediately obvious to new programmers. - -[Notepad++](https://notepad-plus-plus.org/) is a popular text editor for both beginners and advanced users who prefer a simpler interface. -Other editors we recommend can be found [here](https://pythondiscord.com/resources/tools/#editors). - -## Installing Git Bash -Git is a command line program that helps you keep track of changes to your code, among other things. -Many developers use it, and while you may not need it right away, it is useful to install it because it comes with Git Bash. -On the "Select Components" screen, no settings need to be changed. -The next screen will ask what text editor you want to use with Git. Vim is the default choice, though Vim is widely considered difficult to learn, so you may choose to select Notepad++ or whichever text editor you may have installed previously. - -For all remaining screens in the installation, the default selections are fine. - -## Configuring .bashrc -`.bashrc` is a file where we tell Git Bash where the Python executable is. -First, open Git Bash, and as your first command, type `echo ~` and hit enter. -This will most likely print `c/Users/YourUsername` to the terminal. -Navigate to this location in your file explorer, though keep in mind that Windows will display `c/Users/YourUsername` as `C:\Users\YourUsername`. -In this folder, there will be a file called `.bashrc`; open it with your text editor of choice. - -For this step, you will need to remember where you installed Python earlier. -In whichever folder that was, there is a file called `python.exe`; this is the executable that will run your Python programs. -Copy the full path of this file, starting from `C:`. -If you used the example location given earlier, it will be located at `C:\Python\python.exe`. - -In the `.bashrc` file, add a line to the end of the file saying `alias python='C:\\Python\\python.exe`, where `C:\\Python\\python.exe` is the location of your `python.exe` file, but each folder is separated by two backslashes instead of one. -The two backslashes are because a single backslash is used as an [escape character](https://en.wikipedia.org/wiki/Escape_character). -Save the file, and then type `source ~/.bashrc` to activate the change you have made. - -Finally, enter `python -c 'import sys; print(sys.executable)'` into Git Bash. -(If you attempt to copy and paste this into the terminal using Ctrl+V, it might not work, though Shift+Insert will.) -If all the steps have been followed correctly, this will print the location of your `python.exe` file and demonstrate that your environment is set up correctly. -You can hereafter use the `python` command in Git Bash to run any Python program that you write. - -## Running a test program -At any location on your computer, create a file named `hello.py` and open it with your text editor. -The program need only be one line: `print('Hello world!')`. -Save this file. - -To run this program in Git Bash, navigate to where it is saved on your hard drive. -If you know the path to this location, you can use the `cd` command ("cd" stands for "change directory") to navigate to it. -If it's saved to your desktop, `cd /c/Users/YourUsername/Desktop` will take you there. -Otherwise if you have the directory open in your file explorer, you can right click anywhere in the white space of the file explorer window (not on top of a file) and select "Git Bash Here". -Once you're there, type `python hello.py`, and the program will run. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml b/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml new file mode 100644 index 000000000..96c8eb685 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml @@ -0,0 +1,2 @@ +title: Python on Windows +description: Guides related to installing, managing, and troubleshooting Python on Windows operating systems. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md b/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md new file mode 100644 index 000000000..6d66661e8 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/common-issues.md @@ -0,0 +1,174 @@ +--- +title: Common Issues Using Python on Windows +description: A list of common issues with Python on Windows and how to fix them +icon: fab fa-windows +toc: 3 +--- + +### 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. + +### I `pip` installed a package but when running my code I get a `ModuleNotFoundError` + +- #### Are you actually getting a `ModuleNotFoundError`? + + If you are using a code editor such as VSCode or PyCharm you may get a squiggly line under your import saying the + module couldn't be found, it is possible that this is just an mistake by the editor, so try to actually run your + code the way it is to ensure that it actually errors. + + If your code runs fine, you could try restarting your editor. If you have newly installed a module it may just not + have detected it yet. If that doesn't help, you may need to configure your editor to ensure it is looking for the + module in the correct Python environment. See [our guide on virtual + environments](../installing-and-using-python/#virtual-environments) for more information. + +- #### Was the install successful? + + Look out for errors when installing the module you want. If you get an error, that's probably why the import isn't + working, so you should look into it. Often a Google search of the relevant error text will help. + +- #### Did you use the correct module name? + + Double check that you haven't made a typo in the name you are importing, or in what you installed from + [PyPI](https://pypi.org/), you need to make sure you type the name exactly as it should be. + + Also, **the name you should `import` may not be the same as the name you `pip install`**. Check the module's + documentation or PyPI page if you are unsure. Examples of this are: + + - [**opencv-python**](https://pypi.org/project/opencv-python/): You need to `pip install opencv-python`, but the + import has to be `import cv2` + - [**discord.py**](https://pypi.org/project/discord.py/): You need to `pip install discord.py`, but the import has + to be `import discord` + - [**python-dotenv**](https://pypi.org/project/python-dotenv/): You need to `pip install python-dotenv`, but the + import has to be `import dotenv` + - [**Pillow**](https://pypi.org/project/Pillow/): You need to `pip install Pillow`, but the import is + usually `from PIL import Image`. + + Normal imports in Python can't have hyphens (`-`) in them as it would be interpreted as subtraction. So if the + package name has a `-` in it the import will definitely be different. + +- #### Are you installing to the same environment you're running your code from? + + This is a very common issue. When you install a module from PyPI, you will install it into a single Python + environment, the one that the `pip` you invoked is part of. This could be different to the one you are running the + script from if it's using a different Python installation, or a [virtual environment](../installing-and-using-python/#virtual-environments). + + You can tell when you're in a virtual environment because the name of the venv folder will usually be shown in + parentheses at the start of terminal prompts. You can type `deactivate` to get out of it. + [![Venv terminal prompt.](/static/images/content/python-on-windows/venv_prompt.png)](/static/images/content/python-on-windows/venv_prompt.png) + + ##### I'm using PyCharm + + > PyCharm creates a virtual environment for each project by default, so if you're installing a module using Pycharm + > you need to make sure you also run your code through PyCharm. This also applies the other way round, if you want + > to use a module in PyCharm you need to install it through PyCharm. + > + > You can see the exact path of the current Python interpreter, and thus virtual environment, in PyCharm by hovering + > your mouse over the interpreter info menu on the bottom right: + > [![PyCharm python.exe info.](/static/images/content/python-on-windows/pycharm_python_path.png)](/static/images/content/python-on-windows/pycharm_python_path.png) + > + > It's also possible to change PyCharm to use your system environment, see [their guide on configuring your + > interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html) for more information. + + ##### I installed the module using pip from the command line + + > Run `pip -V` and look at the path it returned, which should be in the form + > `\Lib\site-packages\pip`. + > + > Then put `import sys;print(sys.executable);sys.exit(0);` at the top (above imports!) of your python file, and run + > it. The result should be in the form `\python.exe`. + > + > Now compare that `PATH_TO_PYTHON` to the one from `pip -V`. If they're different, this is the cause of the + > `ModuleNotFoundError`. Follow the relevant "I'm running my code with ..." section below for how to fix this. + + ##### I'm running my code with `python` from the terminal. + + > If you are using a virtual environment, ensure you have activated it before running `pip install`. You can test + > this by running `pip -V` and checking the path is the one of your virtual environment. + > + > Alternatively, you can use the `py` command to specify the python version you want to pip install into, e.g. + > `py -3.9 -m pip install numpy`, and to specify the executable you want to run your code with, e.g. + > `py -3.9 my_script.py`. + > + > If your `pip` and `python` commands are referring to different python environments at the same time, it's possible + > your PATH is configured incorrectly. See our [guide for adding Python to PATH](../putting-python-on-path) for + > how to fix this. + + ##### I'm running my code with the button in VSCode + + > To run your code from the same environment you installed Python to, set the VSCode Python interpreter to the one + > at the path you found when running `pip -V` by following [this + > guide](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) (basically + > `Ctrl+Shift+P -> Python: Select Interpreter -> select the one desired`). The path should be in the form + > `PATH_TO_PYTHON\python.exe` + > + > Alternatively, you can pip install to the currently activated environment. If you have configured VSCode to use a + > virtual environment, it should automatically activate it when you open a new terminal, so running the + > `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 + +You pip installed a command line program like [`pyinstaller`](https://pypi.org/project/pyinstaller/) or +[`black`](https://pypi.org/project/black/) that is intended to be run from the command line, but it does not work. Two +common causes for this are: + +- You are using Python from the Microsoft Store ([which we don't recommend](../microsoft-store)). + + To check if this is the case, type `pip -V`. If the path output includes something like + `PythonSoftwareFoundation.Python.3.10_3.10.2288.0_x64__qbz5n2kfra8p0`, you are using Python from the Microsoft + Store. To fix this you will either have to use the full path to the scripts you want to use, or [uninstall the + Microsoft Store Python](../microsoft-store/#uninstalling) and [install Python + properly](../installing-and-using-python) with a [python.org installer](https://www.python.org/downloads). + +- You manually modified your PATH Environment Variable incorrectly + + If you added `Python` to PATH manually through environment variables, it is possible that you only added the + executable but not the `\Scripts` folder. This would cause issues with `pip` and make command line tools not + accessible. Look at our [guide on adding Python to the + PATH](../putting-python-on-path/#advanced-method-manually-edit-the-path) for how to verify and fix this. + +Projects that add a command line program usually work by adding an executable to the `\Scripts` folder of your Python +install (the full path of which is `C:\Users\\AppData\Local\Programs\Python\Python311\Scripts` in a default 3.11 +install). If you checked "Add python.exe to PATH" when installing Python, this folder will have been added to PATH, so +anything there should be runnable directly from the command line. Virtual environments also have their own `\Scripts` +directories that things can be installed to and are effectively on the PATH when the venv is properly activated. + +### 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 +loop](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)), also known as the Python console. This lets +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 +something like Command Prompt or PowerShell. _Not_ in the Python REPL, which usually has `>>>` at the start of each +line. To exit the Python REPL, type `exit()` and press enter. You should then be able to run your commands normally, +unless it was the Python App, in which case it will close completely and you'll need to open a normal terminal +separately. + +### I tried to uninstall Python by deleting the folder, now it doesn't work and I can't reinstall it! + +You should never uninstall your Python installation by deleting the folder it is in. If you have, you may need to edit +Registry Keys to fully remove the installation. Doing this is dangerous and beyond the scope of this guide. + +To uninstall Python properly, run the installer for the version you want to uninstall and select "uninstall". If you no +longer have the installer, you can [re-download it from python.org](https://www.python.org/downloads/windows/) first. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/installing-and-using-python.md b/pydis_site/apps/content/resources/guides/python-guides/windows/installing-and-using-python.md new file mode 100644 index 000000000..81fe4cbb0 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/installing-and-using-python.md @@ -0,0 +1,238 @@ +--- +title: Installing and Using Python on Windows +description: How we recommend installing Python on Windows, and how to use Python Windows features +icon: fab fa-windows +toc: 3 +--- + +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 +Store](https://apps.microsoft.com/store/search/python) is _not_ recommended as [it can cause various +issues](../microsoft-store). + +This guide gives detailed instructions on that [recommended way to install Python on Windows](#recommended-install), +then goes on to discuss [more information about installing Python on Windows](#more-installation-information), and +finally wraps up by explaining some common Windows-specific Python usage, namely the [py launcher](#the-py-launcher), +and how to work with [virtual environments](#virtual-environments). + +You may also want to check out our guides on [Common Issues Using Python on Windows](../common-issues), [Adding Python +to the Windows Path](../putting-python-on-path.md), and [Setting up a Unix-Style Environment on +Windows](../unix-env-on-windows.md). + +## Recommended Install + +Follow the five steps below to install the latest version of Python on Windows. + +(The instructions were written with Windows 10 and Python 3.11.0 in mind, but should be nearly or fully identical with +Windows 11 or other modern versions of Python.) + +> If you want a fresh start, you should check for and uninstall any versions of Python already on your PC, including +> those from the Microsoft Store. This can be done in the ["Apps & features" Windows +> settings](/static/images/content/python-on-windows/ms_store_uninstall.png) (type "apps and features" into the Start +> Menu to find it). Though it's fine to have multiple versions of Python installed at once. It can be useful for testing +> version compatibility or for working on projects made in a certain version. Only uninstall things if you want to. + +1. Go to [python.org/downloads](https://www.python.org/downloads) and click the big yellow "Download Python 3.x.x" + button near the top of the page. That should start the download of the installer (a file like + `python-3.11.0-amd64.exe`) for the latest version of Python. + + If you want a different version or it doesn't work for some reason, you can download the Windows installer you want + from [python.org/downloads/windows](https://www.python.org/downloads/windows). If you still have a [32-bit operating + system](#32-bit-vs-64-bit) you'll need to go here and look for the latest "Windows installer (32-bit)" because the + yellow button downloads the 64-bit installer by default. + + [![Step 1](/static/images/content/python-on-windows/recommended_install_1.png)](/static/images/content/python-on-windows/recommended_install_1.png) + +2. When it finishes downloading, click the file in your browser or find it in your Downloads folder and double-click it + to start the installer. + + [![Step 2](/static/images/content/python-on-windows/recommended_install_2.png)](/static/images/content/python-on-windows/recommended_install_2.png) + +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.) + + [![Step 3](/static/images/content/python-on-windows/recommended_install_3.png)](/static/images/content/python-on-windows/recommended_install_3.png) + +4. Then click the big "Install Now" button. Aside from adding Python to PATH, the rest of the installer defaults are + usually fine, so there's no need to customize the installation unless you have a specific reason to. + + [![Step 4](/static/images/content/python-on-windows/recommended_install_4.png)](/static/images/content/python-on-windows/recommended_install_4.png) + +5. It will take a minute to install and then (hopefully) say "Setup was successful". + + Congrats! You just installed Python! You can close the installer. + + [![Step 5 A](/static/images/content/python-on-windows/recommended_install_5.png)](/static/images/content/python-on-windows/recommended_install_5.png) + [![Step 5 B](/static/images/content/python-on-windows/recommended_install_6.png)](/static/images/content/python-on-windows/recommended_install_6.png) + +### Checking that it Worked + +To test that installing Python worked, you can do what it suggests and search "python" on the Start Menu to find the +Python console app and run some code like `print("Hello, World!")`. + +[![Testing Python console](/static/images/content/python-on-windows/recommended_install_7.png)](/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 +[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), or use `python somefile.py` to run a +Python file. You can use whichever terminal you prefer: Command Prompt, PowerShell, an IDE-integrated terminal, [Windows +Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701), etc. It just has to be a freshly +opened terminal or the commands may not be recognized. + +[![Testing py and python](/static/images/content/python-on-windows/recommended_install_8.png)](/static/images/content/python-on-windows/recommended_install_8.png) + +You can double check what versions of Python and [pip](https://pip.pypa.io/en/stable/) were installed by running +`python -V` or `pip -V` in a terminal: + +[![Checking python and pip versions](/static/images/content/python-on-windows/testing_path_worked_1.png)](/static/images/content/python-on-windows/testing_path_worked_1.png) + +And finally, it's worth searching and opening "IDLE" on the Start Menu, which is the the basic +[IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) that comes with Python. Most people end up using +[PyCharm](https://www.jetbrains.com/pycharm/) or [VSCode](https://code.visualstudio.com/) to program in Python but IDLE +is a great starting point. + +[![Testing IDLE](/static/images/content/python-on-windows/recommended_install_9.png)](/static/images/content/python-on-windows/recommended_install_9.png) + +## More Installation Information + +### Selecting an Installer + +At [python.org/downloads/windows](https://www.python.org/downloads/windows/) there are many different Windows Python +installer options available. A link to the latest release page is listed at the top, for example [the Python 3.11.0 +release page](https://www.python.org/downloads/release/python-3110/) has info about the new 3.11 features, with +downloads at the bottom. Back on the list of all Windows releases, pre-releases are on the right if you want to try +cutting-edge (and possibly unstable) versions of Python, and stables releases are on the left, all the way back to +Python 2.0.1 from 2001. Some minor release versions may not have installers available. + +You should usually select the "Windows installer" option instead of the "Windows embeddable package" when picking what +to get. Check out [the official documentation](https://docs.python.org/3/using/windows.html) for more +details on installing and using Python on Windows. + +### Which Version? + +Current Python versions follow [the form `3.minor.micro`](https://peps.python.org/pep-0440/#final-releases) (similar to +[semantic versioning](https://semver.org/)), for example +[3.11.0](https://www.python.org/downloads/release/python-3110/). "3" is the major number and not about to change. Minor +releases happen [yearly](https://endoflife.date/python) and provide new features and breaking changes, whilst micro +releases are more common and only include bug/security fixes. When people say "Python 3" they they aren't necessarily +specifying a minor or micro version, but you can often assume they mean the latest ones. + +Installing the latest minor version will give you access to Python's newest features. However, some packages may not +support the newest versions straight away, so installing the second latest (for example, installing 3.10 when 3.11 is +the latest) will help you avoid those issues. If you find you want some newer features or your module does not support +your current version, you can always install another version as well. + +You should generally always install the newest micro version, although some may not provide an installer, in which case +you should find the newest one that does. + +### What about Python 2 and 4? + +Python 2 should not be used unless you are absolutely required to for legacy code or school. + +[It was officially sunset January 1, 2020:](https://www.python.org/doc/sunset-python-2) + +> As of January 1st, 2020 no new bug reports, fixes, or changes will be made to Python 2, and Python 2 is no longer +> supported. + +Python 2 code is not _that_ different from Python 3 code, notable differences being that `print` was a statement rather +than a function so it didn't need parentheses, and `input` evaluated the things inputted (unsafe!). Still, it's best +to try to not use learning resources written in Python 2, and definitely don't start new projects in Python 2. + +Python 4 is [not happening anytime soon](https://builtin.com/software-engineering-perspectives/python-4), if ever. + +### 32-bit vs 64-bit? + +Install 64-bit Python unless you have reason not to, such as having an old 32-bit computer. Modern PCs ([and all Windows +11 +PCs](https://answers.microsoft.com/en-us/windows/forum/all/does-microsoft-has-32-bit-version-of-windows-11/3bd76840-4e84-4573-8252-71380ef41bf1)) +are 64-bit. With 32-bit you may run into memory limits if doing intensive operations (Python will be limited to using +4GB of memory), and some installed modules may not offer prebuilt [wheels](https://realpython.com/python-wheels/) for +32-bit, potentially making installs slower or meaning you have to install build dependencies. + +If you get an error when installing 64-bit Python, your computer may not support it. To find out if this is the case, +search "About your PC" in the Start Menu and open the settings page. Then look for the "System Type" option under +"Device Specifications". It should say "64-bit operating system, x64-based processor" if you have support. You need a +64-bit processor and operating system to install 64-bit programs. + +## The py Launcher + +By default, when you install Python on Windows from a [python.org installer](https://www.python.org/downloads/windows/), +it comes with the "py launcher". The py launcher is a command line tool you invoke using the `py` command and it helps +you run a specific version of Python when you have multiple versions installed. + +The `py` command is not mere shorthand for the `python` command. They are separate programs as can be seen in the +"Apps & features" Windows settings. Though running either of them with no arguments will start the Python +[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop). + +The py launcher provides the `py -0` command (or `py --list`) which lists the Python versions you have installed. +`py -0p` does the same but includes the paths to the Python executables. + +For example, on my PC I have Python 3.11 and 3.10 installed, and the py launcher shows it: + +[![py launcher list command](/static/images/content/python-on-windows/py_launcher.png)](/static/images/content/python-on-windows/py_launcher.png) + +The versions are ordered from newest to oldest, and the asterisk (`*`) indicates which version currently running `py` +will call by default (3.11 in my case). Exactly which version that is depends on the following requirements, and may not +be the same version you get when running `python` (if you get any). + +> If an exact version is not given to `py`, the latest is used unless overridden by the following, (in priority +> order): +> +> - An active virtual environment. +> - A [shebang]() line in the script (if present). +> - With a `-2` or `-3` flag and matching PY_PYTHON2 or PY_PYTHON3 environment variable. +> - A PY_PYTHON environment variable. +> - From `[defaults]` in py.ini in your `%LOCALAPPDATA%` folder. +> - From `[defaults]` in py.ini beside py.exe (usually in `C:\Windows`, use `where.exe py` to locate). + +You can give the py launcher an exact version of Python to run (assuming you have it installed) by specifying the major +and minor versions. For example, to invoke Python 3.7, you could run `py -3.7`. You can then pass any arguments on top +of that, for example `py -3.7 myscript.py` to run `myscript.py`, or `py -3.7 -m pip install numpy` to invoke `pip` to +install [NumPy](https://numpy.org/) into Python 3.7. + +If you want can always use `py` instead of `python` and not have any Python versions on the Windows Path at all (check +out [this guide](<(../putting-python-on-path)>) to learn about the Windows Path). Though, once in a while third party +software may want to invoke `python`, so keeping it on the Path is handy. We recommend having your "main" Python version +on the Path so you can invoke it with `python`, and then using `py -X.Y` whenever you want a different version, e.g. +`py -3.7`. + +The official documentation of the `py launcher` can be found +[here](https://docs.python.org/3/using/windows.html#python-launcher-for-windows). Use `py --help` to show help on the +command line. + +The py launcher is not available on GNU/Linux-based platforms such as macOS, but there is [an unofficial version by +Brett Cannon](https://github.com/brettcannon/python-launcher). + +## Virtual Environments + +Virtual environments ("venvs") are a way of giving each of your Python projects their own space to install dependencies +in, so different projects can have different versions of the same dependencies. For example, suppose you are working on +two websites that both use the Python web-framework [Django](https://www.djangoproject.com/download/). One site is older +and requires Django 3.2, and the other is newer and requires Django 4.1. If you install Django globally, no matter if +you install 3.2 or 4.1, one or the or the other of the projects will have the wrong version. If instead you make a +virtual environment for each project, you can install the required Django version for each separately. + +Virtual environments are not exclusive to Windows, but the commands to use them can differ across operating +systems. Check out the [official docs](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) and +the builtin [venv](https://docs.python.org/3/library/venv.html) module for more details, but there are basically 3 +important venv commands. Run them once you `cd` into your project folder. + +1. Create a virtual environment: `python -m venv .venv` +2. Activate a virtual environment: `.venv\Scripts\activate` +3. Deactivate a virtual environment: `deactivate` + +(".venv" is a common name for the folder to put virtual environment files in but other names are allowed too.) + +Once you activate a virtual environment, anything you `pip install` will be installed only to that environment. You +should be able to tell when a venv is active because `(.venv)` or similar will appear at the start of terminal +prompts. + +If your editor/IDE has handling for virtual environments, it's worth looking into how it works. +[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/), +[Pipenv](https://pipenv.pypa.io/en/latest/), and [Virtualenv](https://virtualenv.pypa.io/en/latest/) are other popular +tools for managing dependencies and virtual environments. Answers to [this Stack Overflow +question](https://stackoverflow.com/questions/41573587) explain all the confusingly similar names and much more. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md new file mode 100644 index 000000000..96a540238 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md @@ -0,0 +1,79 @@ +--- +title: Why Not to Install Python from the Microsoft Store +description: The drawbacks of installing the Microsoft Store versions of Python +icon: fab fa-windows +--- + +[](/static/images/content/python-on-windows/ms_store_drake.png) + +Microsoft provides versions of Python for Windows [on the Microsoft +Store](https://apps.microsoft.com/store/search/python) as an alternative to using the installer from +[python.org](https://www.python.org). **We recommend you install Python on Windows using the [full installer +from python.org](https://www.python.org/downloads), and not from the Microsoft store wherever possible!** + +Installing Python from [python.org](https://www.python.org) does not normally require administrator privileges, but if +for whatever reason don't have permission to install it, don't feel bad if you get the Microsoft Store version instead. +Better some Python than no Python. + +You can follow [this guide](../installing-and-using-python) to install Python from python.org and more Python Windows +releases can be found [here](https://www.python.org/downloads/windows). + +Here are some common issues with using Python from the Microsoft Store: + +- #### Command line tools won't work + + Most command line tools, like [`black`](https://pypi.org/project/black/) or + [`pyinstaller`](https://pypi.org/project/pyinstaller/), won't work directly (without specifying the full path, or + invoking them as a module if they allow it). This happens because they normally work by adding an executable to the + `\Scripts` directory, which isn't added to Path on the Microsoft Store version of Python. + +- #### It can cause issues with permissions + + Some modules and scripts won't work with it because of restricted permissions. This is explained [in the Python + documentation](https://docs.python.org/3/using/windows.html#redirection-of-local-data-registry-and-temporary-paths) + +- #### It can cause Path confusion + + Path is the Windows environment variable that determine what programs run when you type commands in terminals. + (Actually there are two Paths, a user one and a system one that has precedence, but they get [combined when + used](https://superuser.com/a/878382/935845).) With Python from the Microsoft Store installed, your `python`, `py`, + and `pip` commands may get mixed up with the python.org ones, depending on the order and contents of Path. + + The Path entry for the Microsoft Store is `C:\Users\\AppData\Local\Microsoft\WindowsApps`. The entries for the + full python.org install are commonly `C:\Users\\AppData\Local\Programs\Python\Python311` and + `C:\Users\\AppData\Local\Programs\Python\Python311\Scripts` (for Python 3.11). If for some reason you want + both installed, put the ones you want the commands for higher up in Path. + + You can find the path of the executable for a version of Python by running `import sys; print(sys.executable)` in + it. + + You can learn more about the Windows Path in [this guide](../putting-python-on-path). + +- #### Confusing app execution alias behaviour + + Typing `python` into a terminal when it is not already installed or not properly on Path may open up the Microsoft + Store to the Python app, pushing you to install it and confusingly hiding the command not found error that would + normally happen. + + You can change this behavior by searching "Manage app execution aliases" in the Start menu and toggling off "App + Installer" for python.exe (and for python3.exe do do the same for the `python3` command). + +- #### You can only get certain versions + + The Microsoft Store Python versions are listed simply like 3.10 rather than 3.10.8 (though it may be 3.10.8 + under the hood). If you know you need a different [micro version](https://peps.python.org/pep-0440/#final-releases), + e.g. 3.10.7, you'll need to [install from python.org](https://www.python.org/downloads/windows/). + + Additionally, Python 3.7 is the earliest version of Python on the Microsoft Store ([and the description mentions it + may be unstable](https://apps.microsoft.com/store/detail/python-37/9NJ46SX7X90P)). Generally you should be using the + latest Python version you can but if you ever need earlier than 3.7 for testing or for working on older code, the + store can't help. + +## Uninstalling + +If you have the Microsoft Store version of Python and want to uninstall it, you can search "uninstall" in the Start menu +to open up the "Apps & features" settings and filter by "python". The Python app that has a console in the icon and +"Python Software Foundation" under the name is the Microsoft Store one. Click it and hit Uninstall. + +[![Which version is which when uninstalling Python](/static/images/content/python-on-windows/ms_store_uninstall.png)](/static/images/content/python-on-windows/ms_store_uninstall.png) diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md b/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md new file mode 100644 index 000000000..18a3d787d --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/putting-python-on-path.md @@ -0,0 +1,254 @@ +--- +title: Adding Python to the Path +description: How to make sure Python is properly on the Windows Path environment variable +icon: fab fa-windows +toc: 2 +--- + +If you're on Windows and know you have [Python installed from python.org](https://www.python.org/downloads/) ([our +recommended way](../installing-and-using-python)) but you're still getting errors like + +```text +pip : The term 'pip' is not recognized as the name of a cmdlet, function, script file, or operable program. +``` + +when trying to run a [`pip`](https://pip.pypa.io/en/stable/) or [`pyinstaller`](https://pypi.org/project/pyinstaller/) +command, or running `python` [unexpectedly opens up the Microsoft +Store](../microsoft-store#confusing-app-execution-alias-behaviour), the issue is likely that your Windows Path +environment variable is improperly configured for Python. This just means Windows doesn't know how to find your Python +installation. + +The Path (or PATH) environment variable is what Windows uses to locate executables needed on the command line. Whenever +you type a command name in your terminal, like `python` or `pip`, the terminal looks for a program of the same name in +the folders listed in the Path, so the command can be run. + +The [python.org Python installer](https://www.python.org/downloads/) provides an option to add Python to your Path +automatically, although it is not checked by default so many people miss it: + +[![Add Python to path installer checkbox.](/static/images/content/python-on-windows/installer_path_checkbox.png)](/static/images/content/python-on-windows/installer_path_checkbox.png) + +But don't worry, you can have the installer add it after the fact, or add it yourself! Continue on just below to the +[safe method](#safe-method-let-the-installer-add-python-to-path) to have the installer put Python on Path for you. Or, +if you want to learn a handy Windows programming skill, skip to the [advanced +method](#advanced-method-manually-edit-the-path) that explains how to edit the Path manually. + +## Safe method: Let the installer add Python to Path + +The easiest and safest way to add Python to Path is by rerunning the installer. For this you will need the same +installer you used to install Python, which you can download again if needed from +[python.org](https://www.python.org/downloads/windows/), or it may still be in your Downloads folder (it's a file named +something like `python-3.11.0-amd64.exe`). + +Once you have it, here are the steps to modify the installation to add Python to Path: + +1. Run the installer by double clicking it. + + [![Step 1](/static/images/content/python-on-windows/safe_path_method_1.png)](/static/images/content/python-on-windows/safe_path_method_1.png) + +2. Select "Modify". (If you don't see the "Modify/Repair/Uninstall" screen then you likely have the wrong installer.) + + [![Step 2](/static/images/content/python-on-windows/safe_path_method_2.png)](/static/images/content/python-on-windows/safe_path_method_2.png) + +3. Hit "Next" to move past the "Optional Features" screen. + + [![Step 3](/static/images/content/python-on-windows/safe_path_method_3.png)](/static/images/content/python-on-windows/safe_path_method_3.png) + +4. Check the "Add Python to environment variables" checkbox on the "Advanced Options" screen. + + [![Step 4](/static/images/content/python-on-windows/safe_path_method_4.png)](/static/images/content/python-on-windows/safe_path_method_4.png) + +5. Hit install! + + [![Step 5](/static/images/content/python-on-windows/safe_path_method_5.png)](/static/images/content/python-on-windows/safe_path_method_5.png) + +Then, after a moment, it should say "Modify was successful" and you can close the installer. Python should now be on +your Path! **You will need to restart any terminals or editors you have open before they detect the change.** + +(These steps are for the Python 3.11 and installer may differ slightly for other versions. Also, for step 1, if +preferred, you can find your Python installation in the "Apps & features" Windows settings and hit "Modify" there, but +will still need to locate the installer exe at step 5 if it's not already in Downloads.) + +### Verifying your changes + +To check that it worked, open a fresh terminal — Command Prompt, PowerShell, an IDE-integrated terminal, [Windows +Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701), whichever you prefer, just _not_ the +Python terminal with the `>>>` prompt — and run + +```text +python -V +``` + +and then + +```text +pip -V +``` + +and you should see the versions of Python and pip that you just added to Path: + +[![Checking Python and pip versions.](/static/images/content/python-on-windows/testing_path_worked_1.png)](/static/images/content/python-on-windows/testing_path_worked_1.png) + +Running `Get-Command python` in PowerShell, or `where python` in Command Prompt, you +can see where that terminal is finding the `python.exe` it would run when a `python` command is given: + +[![Get-Command/where Python.](/static/images/content/python-on-windows/testing_path_worked_2.png)](/static/images/content/python-on-windows/testing_path_worked_2.png) + +(`where` in fact lists all the Pythons it finds, even the dummy [app execution +alias](../microsoft-store#confusing-app-execution-alias-behaviour) one that opens the Microsoft Store.) + +You can also run Python with `python` (not `py` as that may start a different version, see more +[here](../installing-and-using-python/#the-py-launcher)), and then after `>>>` in the Python REPL, run + +```py +import sys; print(sys.executable); exit(); +``` + +to see that the exact executable that is currently running Python is what you expect: + +[![Checking Python executable.](/static/images/content/python-on-windows/testing_path_worked_3.png)](/static/images/content/python-on-windows/testing_path_worked_3.png) + +Of course your username will probably not be "r", and your executable path may differ from +`C:\Users\\AppData\Local\Programs\Python\Python311` depending on where you chose to install Python and what +version you have. The last folder will normally be `Python310` for Python 3.10, `Python39` for Python 3.9, etc. But +those differences don't matter if `python` and `pip` and other things like `pyinstaller` (if you've [pip +installed](https://pypi.org/project/pyinstaller/) it) now work for you! + +Hopefully things are indeed working, however, it is possible that, due to having multiple Python versions, or other +mixups, the commands are still not behaving how you expect. If so, read on to learn how to manually edit the Path. (If +you already did that, open a help channel on the [Python Discord server](https://discord.com/invite/python) explaining +everything you've tried so far, and someone will hopefully be able to help.) + +## Advanced Method: Manually edit the Path + +### About the Path + +As mentioned above, the Path (often called "PATH", though it shows up as "Path") is what Windows uses to locate +executables needed on the command line. If it's misconfigured, `python` and `pip` commands may not work as +expected. + +"Path" is the name of a Windows environment variable whose value is simply a list of paths to folders on the system. A +_path_ is just string that locates a folder, like `C:\Program Files\Git\cmd`. An _environment variable_ is a variable (a +thing with a name and a value) that is available to the entire system, or at least to an entire user of the system. + +In fact, the Windows Path is technically _two_ environment variables, two lists of folders: a System one and a User one. +But, as explained [here](https://superuser.com/a/878382), when actually used, the User Path is appended to the System +Path, forming one long list. + +So, how it works is whenever you type a command like `python` into a terminal, the terminal looks for a matching +runnable file like `python.exe` ([or `python.bat`](https://en.wikipedia.org/wiki/Batch_file)) in each of the folders +listed in the Path, starting with the System Path (top to bottom), and then the User Path (top to bottom). It stops +searching on the first one it finds and runs that program with the command line arguments you may have given it, hence +(hopefully) running Python from an installed `python.exe`. + +If it can't find a runnable file that matches the command name, it spits out an error like: + +```text +foobar: The term 'foobar' is not recognized as the name of a cmdlet, function, script file, or operable program. +``` + +Or, in the case of not finding `python`, it may [open up the Microsoft +store](../microsoft-store#confusing-app-execution-alias-behaviour). + +Again, the Path lookup order is: + +> System Path (top to bottom) → User Path (top to bottom) → Command not found error + +### Adding Python to your Path + +Here only the common case of adding Python and the Python Scripts directory to the Windows Path is detailed. However, +knowing how to manually modify the Path is handy beyond just Python for whenever you need to change or debug which +programs run on the command line in Windows. (The less customizable but [safer method is +above](#safe-method-let-the-installer-add-python-to-path) if you missed it.) + +Follow these steps to add Python to the Path. **You will need administrator privileges on your computer.** + +1. First, find the folder path your Python executable is in. There are a few ways to do this: + + **Way 1**: Run `py -0p` on the command line and copy the folder path of the version you want: + + [![Finding exe with py.](/static/images/content/python-on-windows/finding_exe_1.png)](/static/images/content/python-on-windows/finding_exe_1.png) + + **Way 2**: Run `import sys; print(sys.executable)` in Python on your PC and copy the folder path it prints out: + + [![Finding exe in repl.](/static/images/content/python-on-windows/finding_exe_2.png)](/static/images/content/python-on-windows/finding_exe_2.png) + + **Way 3**: Root around a bit in your `C:\Users\\AppData\Local\Programs\Python` folder or wherever you + installed Python to find the path to the folder that has the `python.exe` in it. + + I end up with `C:\Users\r\AppData\Local\Programs\Python\Python311\` (no `python.exe` at the end). + Your path will of course be based on your username (my username is "r") and your version of Python, such as + `C:\Users\ducky\AppData\Local\Programs\Python\Python39\` if your username is "ducky" and you're using Python 3.9. + Copy your path. We'll use it in steps 6 and 7. + +2. [**This step is optional but helpful to see what's going on.**] Copy the folder path from step 1 into the path bar + of Windows File Explorer. In the folder you should be able to see `python.exe`, and in the Scripts subfolder, things + like `pip.exe` and `pyinstaller.exe` (if you have it installed). + + [![Finding exes in folder.](/static/images/content/python-on-windows/finding_exe_3.png)](/static/images/content/python-on-windows/finding_exe_3.png) + + These are the executables we want the command line to be able to find via the Windows Path. + +3. Now, type "environment variables" in the Start menu or Start search box and open the "Edit the system environment + variables" option. + + [![Step 3](/static/images/content/python-on-windows/edit_path_1.png)](/static/images/content/python-on-windows/edit_path_1.png) + +4. Hit the "Environment Variables..." button. + + [![Step 4](/static/images/content/python-on-windows/edit_path_2.png)](/static/images/content/python-on-windows/edit_path_2.png) + +5. Then in a new window you should see two "Path" variables, one under "User variables for <user>" and one under + "System variables". Select one of them (most likely the User Path) and hit the "Edit..." button underneath it. + + [![Step 5](/static/images/content/python-on-windows/edit_path_3.png)](/static/images/content/python-on-windows/edit_path_3.png) + + You should use the User Path (what the screenshots show) for the default installation of Python. In general, only + put things on the System Path if they are installed for all users (e.g. in `C:\Program Files` or `C:\`) and you're + certain they won't overshadow anything in User Paths. **Remember, the System Path takes precedence over the User + Path when commands are looked up.** + + (Don't worry if your variables or Path contents differ a bit from those shown.) + +6. Now a third window opens and this is where the Path is actually edited. It shows the ordered list of the folders on + the Path and you can select the entries, edit them, reorder them, make new ones, delete them and so on. (Don't + delete any unless you know what you're doing!) + + We want to add the Python executable path we found in step 1 as a new entry, so click "New" and paste in the path. + + [![Step 6](/static/images/content/python-on-windows/edit_path_4.png)](/static/images/content/python-on-windows/edit_path_4.png) + +7. We also need to add the Python Scripts directory to the Path to have commands like `pip` and `pyinstaller` work. So + hit "New" and paste in the Python executable path again, and type "Scripts" after it. + + [![Step 7](/static/images/content/python-on-windows/edit_path_5.png)](/static/images/content/python-on-windows/edit_path_5.png) + + (It doesn't matter whether or not they have trailing backslashes.) + +8. Finally, select each of the paths you just added in turn and move them to the very top of the list using the "Move + Up" button. (Their relative order should not matter.) + + [![Step 8](/static/images/content/python-on-windows/edit_path_6.png)](/static/images/content/python-on-windows/edit_path_6.png) + + This step may not be strictly necessary, but remember that command lookup happens in order from top to bottom. + Python is often bundled with other software that may end up on the Path, so there could be another + `python.exe` in one of of the other folders on the path that gets in the way. (This exact thing has happened to me + when I put `C:\Program Files\Inkscape\bin` on my Path, as [Inkscape](https://inkscape.org/) comes with a copy of + Python.) + + > _8.5._ Recall, the System Path comes before the User Path during command lookup, so to be certain you to may want + > to go back and check the "System variables" Path (see step 5) and _carefully_ delete any entry that you're sure is + > a path to a Python executable overshadowing the one you just added. Though please, don't delete any Path entries + > you're aren't certain about! Just in case, for reference, [here are the important looking System Path + > entries](/static/images/content/python-on-windows/system_path_important.png) on my 64-bit Windows 10 PC. + +9. Finish by making sure to hit "OK" on each of the thee "Edit environment variable", "Environment Variable", and + "System Properties" windows, and then you're done! (If you accidentally hit Cancel the changes may not be saved.) + + Python and Python Scripts should now be on your Path! **You will need to restart any terminals or editors you have + open before they detect the change.** + +At this point you can [verify your changes in the same way as detailed above](#verifying-your-changes). Hopefully it +works! + +(These steps were written with Windows 10 and Python 3.11 in mind, but they should be identical or similar for Windows +11 and other recent versions of Python.) diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md new file mode 100644 index 000000000..22ca70d15 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/unix-env-on-windows.md @@ -0,0 +1,92 @@ +--- +title: Setting up a Unix-Style Python Environment +description: How to setup a Unix-style Python environment on Windows ready to start coding in +icon: fab fa-windows +--- + +Many programmers use Linux or macOS operating systems for their work, though newcomers to programming will likely want +to get started on the computer they already own, which will often be running Windows. + +Programmers need to become comfortable using a command prompt (also known as a terminal or shell), and many guides for +both beginning and advanced programming will often tell you certain commands to run. The Windows command prompt has +different names for similar commands that are available on Linux and macOS. This guide will also help you set up a +command prompt called Git Bash, which will support many of the commands available on Linux and macOS. + +## Installing Python + +First you'll need to install Python. We recommend installing from the Python website, you can follow our guide on how to +do this [here](../installing-and-using-python). + +## Installing a text editor + +You will also need a text editor for writing Python programs, and for subsequent steps of this guide. Powerful programs +called integrated development environments (IDEs) like PyCharm and Visual Studio Code contain text editors, but they +also contain many other features with uses that aren't immediately obvious to new programmers. + +[Notepad++](https://notepad-plus-plus.org/) is a popular text editor for both beginners and advanced users who prefer a +simpler interface. Other editors we recommend can be found [here](https://pythondiscord.com/resources/tools/#editors). + +## Installing Git Bash + +[Git](https://git-scm.com/downloads) is a command line program that helps you keep track of changes to your code, among +other things. Many developers use it, and while you may not need it right away, it is useful to install it because it +comes with Git Bash. On the "Select Components" screen, no settings need to be changed. The next screen will ask what +text editor you want to use with Git. Vim is the default choice, though Vim is widely considered difficult to learn, so +you may choose to select Notepad++ or whichever text editor you may have installed previously. + +For all remaining screens in the installation, the default selections are fine. + +## Configuring .bashrc + +`.bashrc` is a file where we tell Git Bash where the Python executable is. First, open Git Bash, and as your first +command, type `echo ~` and hit enter. This will most likely print `c/Users/YourUsername` to the terminal. Navigate to +this location in your file explorer, though keep in mind that Windows will display `c/Users/YourUsername` as +`C:\Users\YourUsername`. In this folder, there will be a file called `.bashrc`; open it with your text editor of choice. + +For this step, you will need to remember where you installed Python earlier. In whichever folder that was, there is a +file called `python.exe`; this is the executable that will run your Python programs. Copy the full path of this file, +starting from `C:`. If you used the example location given earlier, it will be located at `C:\Python\python.exe`. + +In the `.bashrc` file, add a line to the end of the file saying `alias python='C:\\Python\\python.exe`, where +`C:\\Python\\python.exe` is the location of your `python.exe` file, but each folder is separated by two backslashes +instead of one. The two backslashes are because a single backslash is used as an [escape +character](https://en.wikipedia.org/wiki/Escape_character). Save the file, and then type `source ~/.bashrc` to activate +the change you have made. + +Finally, enter `python -c 'import sys; print(sys.executable)'` into Git Bash. (If you attempt to copy and paste this +into the terminal using Ctrl+V, it might not work, though Shift+Insert will.) If all the steps have been followed +correctly, this will print the location of your `python.exe` file and demonstrate that your environment is set up +correctly. You can hereafter use the `python` command in Git Bash to run any Python program that you write. + +## Running a test program + +At any location on your computer, create a file named `hello.py` and open it with your text editor. The program need +only be one line: `print('Hello world!')`. Save this file. + +To run this program in Git Bash, navigate to where it is saved on your hard drive. If you know the path to this +location, you can use the `cd` command ("cd" stands for "change directory") to navigate to it. If it's saved to your +desktop, `cd /c/Users/YourUsername/Desktop` will take you there. Otherwise if you have the directory open in your file +explorer, you can right click anywhere in the white space of the file explorer window (not on top of a file) and select +"Git Bash Here". Once you're there, type `python hello.py`, and the program will run. + +## WSL + +[WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/about) is another increasingly common +way to set up a GNU/Linux-style environment on Windows. It effectively emulates a Linux distribution on Windows, +complete with command line utilities, that you can use alongside your normal Windows programs. (Technically WSL is a +[compatibility layer](https://en.wikipedia.org/wiki/Compatibility_layer), not en emulator.) + +To set up WSL, check out [this installation guide from +Microsoft](https://learn.microsoft.com/en-us/windows/wsl/install). They also have an +[FAQ](https://learn.microsoft.com/en-us/windows/wsl/faq) and a [best practices guide for using WSL in a development +environment](https://learn.microsoft.com/en-us/windows/wsl/setup/environment). The +[part](https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-windows-terminal) about getting [Windows +Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701) is particularly good advice as it lets +you use one app for all your terminals. + +Also check out these guide for using WSL [with VSCode](https://code.visualstudio.com/docs/remote/wsl) and [with +PyCharm](https://www.jetbrains.com/help/pycharm/using-wsl-as-a-remote-interpreter.html). + +(You may have heard of WSL2 specifically. That is now the default and +[recommended](https://learn.microsoft.com/en-us/windows/wsl/compare-versions) version. If someone says "WSL" they're +probably talking about WSL2.) diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_1.png b/pydis_site/static/images/content/python-on-windows/edit_path_1.png new file mode 100644 index 000000000..bf5d4a66d Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_1.png differ diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_2.png b/pydis_site/static/images/content/python-on-windows/edit_path_2.png new file mode 100644 index 000000000..99c6eae52 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_2.png differ diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_3.png b/pydis_site/static/images/content/python-on-windows/edit_path_3.png new file mode 100644 index 000000000..dbc74a97c Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_3.png differ diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_4.png b/pydis_site/static/images/content/python-on-windows/edit_path_4.png new file mode 100644 index 000000000..bae5631d5 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_4.png differ diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_5.png b/pydis_site/static/images/content/python-on-windows/edit_path_5.png new file mode 100644 index 000000000..c03388887 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_5.png differ diff --git a/pydis_site/static/images/content/python-on-windows/edit_path_6.png b/pydis_site/static/images/content/python-on-windows/edit_path_6.png new file mode 100644 index 000000000..e01d15bcb Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/edit_path_6.png differ diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_1.png b/pydis_site/static/images/content/python-on-windows/finding_exe_1.png new file mode 100644 index 000000000..6b46bef18 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/finding_exe_1.png differ diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_2.png b/pydis_site/static/images/content/python-on-windows/finding_exe_2.png new file mode 100644 index 000000000..5c6020ec3 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/finding_exe_2.png differ diff --git a/pydis_site/static/images/content/python-on-windows/finding_exe_3.png b/pydis_site/static/images/content/python-on-windows/finding_exe_3.png new file mode 100644 index 000000000..753d17e84 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/finding_exe_3.png differ diff --git a/pydis_site/static/images/content/python-on-windows/installer_path_checkbox.png b/pydis_site/static/images/content/python-on-windows/installer_path_checkbox.png new file mode 100644 index 000000000..1091c6134 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/installer_path_checkbox.png differ diff --git a/pydis_site/static/images/content/python-on-windows/ms_store_drake.png b/pydis_site/static/images/content/python-on-windows/ms_store_drake.png new file mode 100644 index 000000000..7cb59c8f4 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/ms_store_drake.png differ diff --git a/pydis_site/static/images/content/python-on-windows/ms_store_uninstall.png b/pydis_site/static/images/content/python-on-windows/ms_store_uninstall.png new file mode 100644 index 000000000..40ee954c0 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/ms_store_uninstall.png differ diff --git a/pydis_site/static/images/content/python-on-windows/py_launcher.png b/pydis_site/static/images/content/python-on-windows/py_launcher.png new file mode 100644 index 000000000..d4dfab845 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/py_launcher.png differ diff --git a/pydis_site/static/images/content/python-on-windows/pycharm_python_path.png b/pydis_site/static/images/content/python-on-windows/pycharm_python_path.png new file mode 100644 index 000000000..9c70bcf72 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/pycharm_python_path.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_1.png b/pydis_site/static/images/content/python-on-windows/recommended_install_1.png new file mode 100644 index 000000000..65601cecb Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_1.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_2.png b/pydis_site/static/images/content/python-on-windows/recommended_install_2.png new file mode 100644 index 000000000..54b58a390 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_2.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_3.png b/pydis_site/static/images/content/python-on-windows/recommended_install_3.png new file mode 100644 index 000000000..2e8f45d9d Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_3.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_4.png b/pydis_site/static/images/content/python-on-windows/recommended_install_4.png new file mode 100644 index 000000000..4b35e1220 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_4.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_5.png b/pydis_site/static/images/content/python-on-windows/recommended_install_5.png new file mode 100644 index 000000000..ded0b5ff3 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_5.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_6.png b/pydis_site/static/images/content/python-on-windows/recommended_install_6.png new file mode 100644 index 000000000..b11e62ec1 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_6.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_7.png b/pydis_site/static/images/content/python-on-windows/recommended_install_7.png new file mode 100644 index 000000000..3091ac080 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_7.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_8.png b/pydis_site/static/images/content/python-on-windows/recommended_install_8.png new file mode 100644 index 000000000..a67176702 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_8.png differ diff --git a/pydis_site/static/images/content/python-on-windows/recommended_install_9.png b/pydis_site/static/images/content/python-on-windows/recommended_install_9.png new file mode 100644 index 000000000..1d37f6926 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/recommended_install_9.png differ diff --git a/pydis_site/static/images/content/python-on-windows/safe_path_method_1.png b/pydis_site/static/images/content/python-on-windows/safe_path_method_1.png new file mode 100644 index 000000000..0c09c8105 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/safe_path_method_1.png differ diff --git a/pydis_site/static/images/content/python-on-windows/safe_path_method_2.png b/pydis_site/static/images/content/python-on-windows/safe_path_method_2.png new file mode 100644 index 000000000..bda60efae Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/safe_path_method_2.png differ diff --git a/pydis_site/static/images/content/python-on-windows/safe_path_method_3.png b/pydis_site/static/images/content/python-on-windows/safe_path_method_3.png new file mode 100644 index 000000000..ef438b867 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/safe_path_method_3.png differ diff --git a/pydis_site/static/images/content/python-on-windows/safe_path_method_4.png b/pydis_site/static/images/content/python-on-windows/safe_path_method_4.png new file mode 100644 index 000000000..3cd315d30 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/safe_path_method_4.png differ diff --git a/pydis_site/static/images/content/python-on-windows/safe_path_method_5.png b/pydis_site/static/images/content/python-on-windows/safe_path_method_5.png new file mode 100644 index 000000000..9037bfb17 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/safe_path_method_5.png differ diff --git a/pydis_site/static/images/content/python-on-windows/system_path_important.png b/pydis_site/static/images/content/python-on-windows/system_path_important.png new file mode 100644 index 000000000..1236cf413 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/system_path_important.png differ diff --git a/pydis_site/static/images/content/python-on-windows/testing_path_worked_1.png b/pydis_site/static/images/content/python-on-windows/testing_path_worked_1.png new file mode 100644 index 000000000..5d9677e61 Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/testing_path_worked_1.png differ diff --git a/pydis_site/static/images/content/python-on-windows/testing_path_worked_2.png b/pydis_site/static/images/content/python-on-windows/testing_path_worked_2.png new file mode 100644 index 000000000..465a873ca Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/testing_path_worked_2.png differ diff --git a/pydis_site/static/images/content/python-on-windows/testing_path_worked_3.png b/pydis_site/static/images/content/python-on-windows/testing_path_worked_3.png new file mode 100644 index 000000000..25493102f Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/testing_path_worked_3.png differ diff --git a/pydis_site/static/images/content/python-on-windows/venv_prompt.png b/pydis_site/static/images/content/python-on-windows/venv_prompt.png new file mode 100644 index 000000000..a2f18087c Binary files /dev/null and b/pydis_site/static/images/content/python-on-windows/venv_prompt.png differ