{ "cells": [ { "cell_type": "markdown", "id": "22ff25a7", "metadata": {}, "source": [ "# Python installation\n" ] }, { "cell_type": "markdown", "id": "contents", "metadata": {}, "source": [ "```{contents}\n", ":local:\n", ":depth: 2\n", "```" ] }, { "cell_type": "markdown", "id": "intro", "metadata": {}, "source": [ "Unlike Unix-like systems (macOS and Linux), Windows does not ship with a default Python. It is, however, very common for your computer, Windows or not, to have multiple Python releases installed already. That could have happened because Python adoption has been prevalent and, overtime, the software packages (e.g., Visual Studio IDE, Anaconda, etc.) you use may have bundled Python as a dependency when you install them.\n" ] }, { "cell_type": "markdown", "id": "ef3dbbb9", "metadata": {}, "source": [ ":::{admonition} Terminal & Shell\n", "\n", "This section requires fundamental knowledge about command line interface (CLI), including how to launch the terminal application and how to operate the operating system shell by issuing commands in the system shell.\n", "\n", "- **Terminal**: A terminal is the program you open to access the **shell**. Common terminal programs include PowerShell/Command Prompt on Windows, Terminal on macOS, and Terminal on Linux.\n", "- **Shell**: The shell is what actually interprets and runs your commands, acting as the interface between you and the operating system. Common shells include `PowerShell`/Command Prompt (Windows), `bash` (macOS and Linux), and zsh (macOS).\n", "- **REPL**: A REPL (Read-Eval-Print Loop) is an interactive environment for a specific programming language, not the OS. You type a line of code, it runs immediately, and the result prints right away. Examples include the **Python shell** (`>>>`at the command line), `csharprepl` for C#, and Node.js's built-in REPL. Jupyter Notebook is also built on a REPL: each notebook cell is a REPL to make each notebook a persistent, non-linear, editable document where cells can be run out of order and outputs can include plots and rich media, not just text.\n", ":::\n" ] }, { "cell_type": "markdown", "id": "12ef6ec7", "metadata": {}, "source": [ "## Check Existing Python\n" ] }, { "cell_type": "markdown", "id": "425ece2c", "metadata": {}, "source": [ "Since Python is widely used by other tools and packages, you more than likely have some versions of Python automatically installed in your system when installing other packages. To check which version(s) of Python are already installed on your computer, start the terminal application. \n", "\n", ":::{warning}\n", "If you do not have Python installed and you type `python` in Windows Search bar or `python` in PowerShell then enter, Windows will show you a Microsoft Store suggestion for Python installation. **DO NOT install Python from Microsoft Store.** It usually leads to issues with Python execution permission, `pip` installer, and lack of `py.exe` launcher. Instead, go to next section: [Install Python](#install-python) to learn how to download a standalone Python installer from [python.org](https://www.python.org) and install Python.\n", ":::\n", "\n", "### Start Terminal\n", "Start the terminal application in your computer to use the CLI.\n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "\n", "Launch the terminal application (`Windows PowerShell`) so you can type commands at the system shell prompt (`>` with a flashing vertical bar `|`). \n", "\n", "```powershell\n", "Windows PowerShell\n", "Copyright (C) Microsoft Corporation. All rights reserved.\n", "\n", "Loading personal and system profiles took 1119ms.\n", "PS C:\\Users\\[user]> |\n", "```\n", ":::\n", "\n", ":::{tab-item} macOS\n", "From Spotlight Search, look for the terminal application (`Terminal.app`) and return to launch it so you can type commands at the system shell prompt (`$` or `%` followed by a block):\n", "```bash\n", "Last login: Fri Aug 28 12:18:57 on ttys000\n", "\n", "[user]@[host]:~$ █\n", "```\n", ":::\n", "::::\n", "\n", "### Check Default Python\n", "\n", "Now you are at the command line, issue the commands to check the default Python release. \n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "\n", "To check the default Python version, issue `python --version` and enter. If a Python is installed, you will see the returned Python version information.\n", "```powershell\n", "PS C:\\Users\\[user]> python --version\n", "Python 3.13.7\n", "```\n", "\n", "If no Python is installed, you may see the following error message. Go to next section: [Install Python](#install-python) to learn how to download a standalone Python installer from [python.org](https://www.python.org) and install Python.\n", "```powershell\n", "PS C:\\Users\\[user]>\n", "Python was not found; run without arguments to install from the Microsoft Store, or disable this shortcut from Settings > Apps > Advanced app settings > App execution aliases.\n", "\n", "PS C:\\Users\\[user]>\n", "```\n", ":::\n", "\n", ":::{tab-item} macOS\n", "With macOS, you already have a version of Python shipped with the OS. You may issue the following commands in the system shell to see all the versions of Python you have in the current system. Note that, in most cases, you may need to use `python3` instead of `python`. \n", "\n", "To find the default Python version when you enter `python3` (or `python`) when you enter it at the command line, pass the `--version` option to Python.\n", "```bash\n", "[user]@[host]:~$ python3 --version\n", "Python 3.12.2\n", "```\n", ":::\n", "::::\n", "\n", "### Check Python Installations\n", "\n", "In addition to the default installation, you can check how many Python releases are installed in your computer. \n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "You can use the command-finder (`where`.exe) and the **Python Launcher** for Windows (`py`.exe) to see the current Python installation(s) in Windows PowerShell. \n", "\n", "The `where.exe` command finder shows all Python installations and their installation paths:\n", "\n", "```powershell\n", "PS C:\\Users\\[user]> where.exe python\n", "PS C:\\Users\\[user]\\workspace\\py> where.exe python\n", "C:\\Users\\[user]\\AppData\\Local\\Programs\\Python\\Python312\\python.exe\n", "C:\\Users\\[user]\\AppData\\Local\\Programs\\Python\\Python313\\python.exe\n", "C:\\Users\\[user]\\AppData\\Local\\Programs\\Python\\Python310\\python.exe\n", "C:\\Users\\[user]\\AppData\\Local\\Microsoft\\WindowsApps\\python.exe\n", "PS C:\\Users\\[user]\\workspace\\py>\n", "```\n", "\n", "The Python Launcher shows the version information and the *launcher default* Python version (the entry with `*`). You can use `py -0` or `py --list` for this.\n", "```powershell\n", "PS C:\\Users\\[user]> py -0\n", " -V:3.13 Python 3.13 (64-bit)\n", " -V:3.13-arm64 Python 3.13 (Store)\n", " -V:3.12 Python 3.12 (64-bit)\n", " -V:3.10 * Python 3.10 (64-bit)\n", "PS C:\\Users\\[user]>\n", "```\n", ":::\n", "\n", ":::{tab-item} macOS\n", "\n", "To check all the installed python versions and their installation paths, use the `which` command (note that this gives you the installations records in the `PATH` environment variable):\n", "```bash\n", "[user]@[host]:~$ which -a python python3\n", "/opt/homebrew/bin/python3\n", "/usr/local/bin/python3\n", "/usr/bin/python3\n", "/opt/homebrew/bin/python3\n", "[user]@[host]:~$\n", "```\n", "\n", "To see the version information for the installations above, use the following code and enter.\n", "```bash\n", "[user]@[host]:~$\n", "for p in $(which -a python python3); do\n", " echo \"$p -> $($p --version 2>&1)\"\n", "done\n", "\n", "```\n", "\n", "You will see the output with version information as below.\n", "```bash\n", "[user]@[host]:~$\n", "for p in $(which -a python python3); do\n", " echo \"$p -> $($p --version 2>&1)\"\n", "done\n", "/opt/homebrew/bin/python3 -> Python 3.14.5\n", "/usr/local/bin/python3 -> Python 3.12.10\n", "/usr/bin/python3 -> Python 3.9.6\n", "/opt/homebrew/bin/python3 -> Python 3.14.5\n", "[user]@[host]:~$\n", "```\n", "\n", "To see the Python installations through Homebrew (recommended), issue the commands: \n", "```bash\n", "[user]@[host]:~$ brew list | grep python@\n", "python@3.12\n", "python@3.13\n", "python@3.14\n", "```\n", "\n", "Actually, all your Homebrew Python installations are in `/opt/homebrew/Cellar/` with symbolic links in `/opt/homebrew/opt/`. You can `cd` into those folders and `ls -l python*` to see all of them listed. \n", ":::\n", "::::" ] }, { "cell_type": "markdown", "id": "329b64c9", "metadata": {}, "source": [ "(install-python)=\n", "## Install Python\n", "\n", "If there is not current Python installation on your computer, or if you would like to install a current or a specific version of Python, follow the instructions here to install it. For both Windows and macOS operating systems, multiple Python installation usually does not cause problems.\n", "\n", "```{note}\n", "If you have already installed Python through the **Microsoft Store**, you are advised to perform a python.org installation following the instructions here. \n", "```\n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "\n", "Visit [python.org/downloads](https://www.python.org/downloads/) and you should see a big yellow button saying \"Download Python install manager.\" **DO NOT install** this `.msix` package version. This is a community-maintained Microsoft Store installation package and may have issues with file write permissions and certain path behaviors because it's a Store app. \n", "\n", "Instead, below the big yellow Download button, find **Or get the standalone installer for [Python 3.major.minor](https://www.python.org/ftp/python/3.14.7/python-3.14.7-amd64.exe)**. The Python 3.major.minor is the most recent *stable* release and would look like **Python 3.14.7**. Click on **Python 3.14.7** to install the standalone installer, which is a python.org release and is a larger `.exe` file. \n", "\n", "If you would like to choose a specific release version, which sometimes is required by certain software packages, go to [python.org/downloads/windows/](https://python.org/downloads/windows/), find the release of your choice, and you choose the right Windows installer.\n", "\n", "After the download is complete, click on the `python-*major*.*minor*.*micro***.exe**` (`python-3.14.7-amd64.exe` in this case) installer file to start the installation. You will see the first installation screen as below. Make sure you check both checkboxes:\n", " - **Use admin privileges when installing py.exe (this enables py.exe to manage all Python installations)**\n", " - **Add python.exe to the PATH environment variable (this sets this installation as the default Python)**\n", "\n", "```{figure} ../../../figures/python_install_windows_3.14.7.png\n", ":alt: python_windows_install\n", ":width: 400px\n", ":name: python_windows_install\n", "Python Installation Options in Windows\n", "```\n", "\n", "Click on **Install Now** to start installation. Note that here you see the installation path under Install Now. It should be something like `C:\\Users\\[user]\\AppData\\Local\\Programs\\Python\\Python314`. \n", "\n", "You will then answer \"Yes\" to continue on next window, then you will see two other installation windows: *Setup Progress* and *Setup was successful* to click on *Close* to complete the installation. \n", "\n", ":::\n", "\n", ":::{tab-item} macOS\n", "Go to [python.org/downloads](https://www.python.org/downloads/). The website will auto-detect your OS and gives you the latest stable release. Click the big yellow \"Download Python 3.major.minor\" (something like *Download Python 3.14.7*) download button to download the Python installer. The installer file extension is `.pkg`. \n", "\n", "If you would like to choose a specific release version, which sometimes is required by certain software packages, go to [python.org/downloads/macos/](https://python.org/downloads/macos/), find the release of your choice, and you choose the right macOS installer.\n", "\n", "After the download is complete, click on the `python-*major*.*minor*-macos11.pkg` (python-3.14.7-macos11 in this case) installer file to start the installation. You will see the first installation screen as below. \n", "\n", "```{figure} ../../../figures/python_install_macos_3.14.7.png\n", ":alt: python_macos_install\n", ":width: 400px\n", ":name: python_macos_install\n", "Python Installation Window in macOS\n", "```\n", "You click on *Continue* to continue the installation. You will see the windows for Read Me and License, which you both click on *Continue* to the software license agreement, which you *Agree* to the installation window, then you click on *Install* to install. After the *Running package scripts window*, you will see a *successfully installed* window for you to close the installer. \n", "\n", "Upon successful installation of Python, a Finder window will open to show you the location of the installation, which should be `/Applications/Python 3.14/`. \n", "\n", ":::\n", "::::" ] }, { "cell_type": "markdown", "id": "787ef975-0adc-4a5d-b414-26df67390eb4", "metadata": {}, "source": [ "## Choose Python Version\n", "\n", "### Choose Python version temporarily\n", "\n", "When you have more than one Python version installed, sometimes you need to control the version of Python that you use for your projects. If the default Python is different from the desired version, which happens often, you may use the Python version **suffixes** to designate the Python version to run. This helps, e.g., when you want to use a specific version of Python for your specific virtual environment.\n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "You may use the Python launcher to decide which Python version to use by appending the major and minor version number of the installed Python to the launcher: `py -*major*.*minor*` (or `py -V:*major*.*minor*`). \n", "\n", "Supposed that your Python Launcher (`py.exe`) has a default Python of 3.10. When you enter `py` to start Python, you always get the default launcher version:\n", "\n", "```powershell\n", "PS C:\\Users\\[user]\\workspace\\py> py\n", "Python 3.10.10 (tags/v3.10.10:aad5f6a, Feb 7 2023, 17:20:36) \n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", "\n", "You may choose to run a specific installed version, such as 3.14, by running `py -3.14` to get to the version of Python shell:\n", "```powershell\n", "PS C:\\Users\\[user]\\workspace\\py> py -3.14\n", "Python 3.14.7 (tags/v3.14.7:bcee1c3, Aug 14 2026, 14:15:11) \n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", "\n", "Usually, the newly installed version will be the default versions when you run `python` (first `python.exe` found in PATH variable) instead of `py` launcher. You can therefore just use `python` to use the PATH default version if that is what you want. The version of your default `python`.exe can be found by issuing `python --version`.\n", "\n", "```powershell\n", "PS C:\\Users\\[user]> python --version\n", "Python 3.14.7\n", "PS C:\\Users\\[user]> python\n", "Python 3.14.7 (tags/v3.14.7:823f032, Aug 5 2026, 10:51:32) [MSC v.1944 64 bit (AMD64)] on win32\n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", ":::\n", "\n", ":::{tab-item} macOS\n", "You may choose to decide which Python version to use by appending the major and minor version number of the installed Python to python: `python3 -*major*.*minor*`. \n", "\n", "Supposed that your default Python of 3.14.5. When you enter `python3` to start Python, you get the default launcher version, which you can confirm using `python3 --version`.\n", "\n", "```bash\n", "[user]@[host]:~$ python3 --version\n", "Python 3.14.5\n", "[user]@[host]:~$ \n", "```\n", "\n", "```bash\n", "[user]@[host]:~$ python3\n", "Python 3.14.5 (main, May 10 2026, 10:21:34) [Clang 21.0.0 (clang-2100.0.123.102)] on darwin\n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>> \n", "```\n", "\n", "Now suppose you want to use a specific non-default installed version, such as 3.12. You issue `python3.12` to get to the version of Python shell:\n", "```bash\n", "[user]@[host]:~$ python3.12\n", "Python 3.12.13 (main, Mar 3 2026, 12:39:30)\n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", ":::\n", "::::" ] }, { "cell_type": "markdown", "id": "b33e8667", "metadata": {}, "source": [ "### Set Default Python Version\n", "\n", "You can also change the system default Python version for the command `python` or `python3` by modifying the path entries in the operating system's PATH environment variable (restarting the computer may be needed).\n", "\n", "::::{tab-set}\n", ":::{tab-item} Windows\n", "\n", "In Windows, you set up the desired Python installation to default by moving its path entry to the top of the PATH environment variable:\n", "\n", "1. In Windows Search, search for \"environment variable\" to find and click on the \"Edit the system environment variables\" that shows up. Click on it and you will see the \"System Properties\" window.\n", "```{figure} ../../../figures/PATH_Windows_System_Properties.png\n", "---\n", "width: 450px\n", "name: windows_system_properties\n", "---\n", "Windows System Properties\n", "```\n", "\n", "2. Click on the \"Environment Variables\" button near the bottom of the System Properties window. The Environment Variables window will show up.\n", "```{figure} ../../../figures/PATH_Windows_environment-variables.png\n", "---\n", "width: 450px\n", "name: windows_environment_variables\n", "---\n", "Windows Environment Variables\n", "```\n", "\n", "3. In the Environment Variables window, click to highlight \"Path\" in the \"User variables for [USER]\" pane.\n", "4. Click the \"Edit\" button to bring up the \"Edit environment variables\" window.\n", "```{figure} ../../../figures/PATH_Windows_Edit-environment-variables.png\n", "---\n", "width: 450px\n", "name: windows_edit_environment_variables\n", "---\n", "Windows Edit Environment Variables\n", "```\n", "\n", "5. Using the Move Up and Move Down button on the right to move your desired Python version entry (e.g., `C:\\Users\\tychen\\AppData\\Local\\Programs\\Python\\Python314\\Scripts\\` and `C:\\Users\\tychen\\AppData\\Local\\Programs\\Python\\Python314\\` for Python 3.14) to the top of the list. \n", "6. You may add new Python version entries to the PATH. Use th New button to add new installed Python path entries (e.g., `C:\\Users\\tychen\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\` and `C:\\Users\\tychen\\AppData\\Local\\Programs\\Python\\Python312\\`) to the environment variables and use the Move Up and Move Down buttons to make sure your desired Python version is at the top of the list.\n", "7. You can edit existing Python path entries using the Edit button. You may, for example, change the top entry from version 3.14 to 3.12. \n", "\n", "```{figure} ../../../figures/python_EV_order.png\n", "---\n", "width: 450px\n", "name: python_EV-order\n", "---\n", "The top Python path is the default Python\n", "```\n", "\n", "This will point the default `python` to your desired version; in this case, Python 3.12:\n", "\n", "```bash\n", "PS \\\\Users\\[user]> python\n", "Python 3.12.2 (tags/v3.12.2:6abddd9, Feb 6 2024, 21:26:36) \n", "[MSC v.1937 64 bit (AMD64)] on win32\n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", ":::\n", "\n", ":::{tab-item} macOS\n", "### macOS\n", "\n", "If you are using macOS, you can change which Python installation is found first by modifying your `PATH` environment variable.\n", "\n", "1. Check which Python commands are currently available:\n", "\n", "```bash\n", "which python\n", "which python3\n", "which python3.12\n", "\n", "python3 --version\n", "```\n", "\n", "For example:\n", "\n", "```text\n", "[user]@[host]:~$ which python\n", "[user]@[host]:~$ which python3\n", "/opt/homebrew/bin/python3\n", "[user]@[host]:~$ which python3.12\n", "/opt/homebrew/bin/python3.12\n", "```\n", "\n", "If `which python` produces no output, the `python` command is not currently available on your `PATH`.\n", "\n", "2. Open your shell configuration file with the `nano` editor:\n", "\n", "```bash\n", "nano ~/.zshrc # if using zsh\n", "nano ~/.bashrc # if using bash\n", "```\n", "\n", "> **Note:** `zsh` is the default shell on recent versions of macOS.\n", "\n", "3. Add the directory for your preferred Python version to the beginning of `PATH`.\n", "\n", "If Python 3.12 was installed using the **python.org macOS installer**:\n", "\n", "```bash\n", "export PATH=\"/Library/Frameworks/Python.framework/Versions/3.12/bin:$PATH\"\n", "```\n", "\n", "If Python 3.12 was installed using **Homebrew**:\n", "\n", "```bash\n", "export PATH=\"$(brew --prefix python@3.12)/libexec/bin:$PATH\"\n", "```\n", "\n", "Using `brew --prefix` avoids hard-coding the Homebrew installation directory, which may differ between Apple Silicon and Intel Macs.\n", "\n", "4. Apply the changes:\n", "\n", "```bash\n", "source ~/.zshrc # if using zsh\n", "source ~/.bashrc # if using bash\n", "```\n", "\n", "5. Verify the Python version and executable location:\n", "\n", "```bash\n", "python3 --version\n", "which python3\n", "```\n", "\n", "Or, you may simply set an alias in your configuration files (such as ~/.bashrc) by adding the line:\n", "```bash\n", "alias python='python3.12'\n", "```\n", ":::\n", "::::" ] } ], "metadata": { "jupytext": { "cell_metadata_filter": "-all" }, "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.7" } }, "nbformat": 4, "nbformat_minor": 5 }