Using Python on Windows

python_on_windows.md

Python on Windows

Table of Contents

• Using the py Launcher
• Notes
• Common Issues
• Clean Up Existing Installs
  • Disable App Execution Aliases
  • Uninstall Windows Store Python
  • Remove Python From PATH
• Uninstalling Python
• Installing Correctly

Using the py Launcher

Recommended reading: https://docs.python.org/3/using/windows.html#python-launcher-for-windows

General usage:

• py instead of python or python3
• py -m pip instead of pip or pip3
• py -X.Y like py -3.10 to use a specific installed version

Note: Python 3.11+ includes an updated py launcher with the -V:X.Y flag, which may be preferable going forward.

py -0 can be used to list (non-Store) installations of Python

py -0p can be used to list installations including their path

An asterisk (*) at the end indicates the default interpreter used.

py -X.Y can be used to invoke a specific installed interpreter by version

The py launcher even supports virtual environments.

py -X.Y can be used to invoke the global interpreter while a venv is active.

Continue reading for examples of why this should be used, how to cleanup existing installations to prevent future confusion, and options to select during installation.

Notes

Python on Windows is difficult to get right, especially just starting out.

To ensure the fewest issues:

• disable the python.exe app execution aliases that redirect to the Store
• do not install Python from the Windows Store
• do not add Python to your Path (user or system)
• only install Python from https://python.org/
• only use the py launcher

Note about command-line examples

4 different interpreters are installed with various configurations to demonstrate issues.

Python 3.10 (not from Windows Store) is the only version installed "correctly" as described by this guide.

• Python 3.8
  • installed for all users
  • added to path
  • installed without pip
• Python 3.9
  • installed for current user
  • added to path
  • installed with pip
• Python 3.10
  • installed for current user
  • not added to path
  • installed with pip
• Python 3.10
  • installed from Windows Store

Common Issues

python and pip can refer to different environments.

In this example, you can see python is for Python 3.8 and pip is for Python 3.9.

You can use the where command in Command Prompt or Get-Command in Powershell to find where an executable is.

In this example, you can see python is found in 3 places, but pip is only found in 2.

Clean Up Existing Installs

Disable App Execution Aliases

Windows 10 and 11 have built-in python.exe and python3.exe aliases that redirect you to the Windows Store.

1. Open App Execution Alias settings

2. Disable the python aliases

Uninstall Windows Store Python

Open Windows app settings, search "python", and uninstall any versions of Python that do not indicate whether they are 32-bit or 64-bit.

For example, the one highlighted here.

Remove Python From PATH

1. Open Environment Variable Settings

We only care about the Path environment variable, for both the user and system.

2. Check user Path variable

Remove any Python-related paths with a version number like the highlighted ones.

Be sure not to remove ...\Python\Launcher if it exists.

3. Check system Path variable

Remove any Python-related paths with a version number like the highlighted ones.

If you followed the above steps

Skip ahead to Installing Correctly to learn how to install in the future without causing issues.

Uninstalling Python

Open Windows app settings, search "python", and uninstall all versions of Python.

Installing Correctly

Download the installer for the version you want from python.org.

Go through installation as normal, change options as you see fit, but do not change any of the highlighted options.

If the highlighted options in your installer do not match the screenshots, change them to match.

You have 2 options here:

• "Install Now" and skip ahead to Using the py launcher
• "Customize installation" and continue

If you have the option to "Disable path length limit", it's recommended to do so.

There are very few cases where it would be detrimental to enable, but you're unlikely to encounter these.

See https://stackoverflow.com/a/52824569 for a brief explanation and some things it may break.

As sees in the first py launcher screenshot, it selected 3.10 by default without intervention, and appears to order them correctly.
In addition, py -3.1 does not launch 3.10 for me.

C:\Users\mike > py -3.1
Python 3.1 not found!
Installed Pythons found by C:\WINDOWS\py.exe Launcher for Windows
 -3.10-64 *

Requested Python version (3.1) not installed, use -0 for available pythons