From 9e632dc1391e5220ff859ee414395586e2ef4003 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Mon, 20 Oct 2025 07:59:56 -0700 Subject: [PATCH 1/8] add rumdl config --- .rumdl.toml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .rumdl.toml diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 0000000..5cec1d1 --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,26 @@ +# Global settings +line-length = 10000 +exclude = ["node_modules", "build", "dist"] +respect-gitignore = true + +# Disable specific rules +disabled-rules = ["MD013", "MD033"] + +# Configure individual rules +[MD007] +indent = 2 + +[MD013] +line-length = 10000 +code-blocks = false +tables = false + +#[MD025] +#level = 1 +#front-matter-title = "title" + +[MD044] +names = ["rumdl", "Markdown", "GitHub"] + +[MD048] +code-fence-style = "backtick" \ No newline at end of file From 33f38abe8b28703779a5920f1fbf65a991c9b628 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Wed, 10 Dec 2025 16:47:41 -0800 Subject: [PATCH 2/8] Modernize Python installation guide for 2025 with uv - Replace 10 different installation methods with unified uv approach - Update target Python version from 3.12 to 3.14 - Add sections for virtual environments and multiple Python versions - Remove outdated options (Anaconda, Chocolatey, Homebrew, building from source) - Reduce guide from 454 lines to ~180 lines --- install-python.md | 464 +++++++++++++--------------------------------- 1 file changed, 133 insertions(+), 331 deletions(-) diff --git a/install-python.md b/install-python.md index c46f35c..73f32e5 100644 --- a/install-python.md +++ b/install-python.md @@ -2,451 +2,253 @@ -Welcome soon to be Python user! Python is one of the easiest programming languages to learn and grow with. But there are a few bumps right at the beginning. **One of these bumps is to make sure you have Python installed** and that it's a sufficiently new version (generally 3.10+ is solid these days). +Welcome soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.12+ is recommended these days). -Because how you install and verify Python varies by operating system, we've put together this short guide. It's goal is to give you exposure to the various ways on your operating system to **install and maintain Python in a concise and no-nonsense manner**. So with out further ado, let's get you setup! +Good news! In 2025, installing Python has become incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)** -- a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python. -## Step 1. Go To Your Operating System +## The Modern Approach: Install uv, Then Python -As mentioned above, how you verify Python and subsequently install it is specific to the operating system. So jump to: +The process is just two steps: + +1. **Install uv** (one command) +2. **Install Python with uv** (one command) + +That's it! Jump to your operating system to get started: * [**Windows**](#windows) * [**macOS**](#macos) -* [**Linux**](#linux) +* [**Linux**](#linux) _________________________ ## Windows -### Step 2. Do you have Python? Let's check +### Step 1. Install uv -To determine if you have Python installed, open the [**command prompt**](https://www.lifewire.com/how-to-open-command-prompt-2618089) or (preferred) install [**new Windows Terminal**](https://devblogs.microsoft.com/commandline/introducing-windows-terminal/) from the [**Microsoft Store**](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab). +Open [**PowerShell**](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell) or [**Windows Terminal**](https://apps.microsoft.com/detail/9n0dx20hk701) and run: -Verify you have Python, in the command prompt / terminal, type **python -V** (capital V): - -``` -C:\users\username\> python -V +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` -The output should be one of the following (*version numbers will vary*). **C:\users\username\> is not typed** - Windows displays this as part of the terminal UI. +After installation completes, **close and reopen your terminal** for the changes to take effect. -#### Success, you have Python +### Step 2. Install Python -``` -C:\users\username\> python -V -Python 3.12.0 -``` +Now install Python 3.14 with a single command: -If you see this and the reported version number is sufficiently high (often 3.9 or higher), **you are good to go**. +```powershell +uv python install 3.14 +``` -#### 2.7? Uh oh, your Python is badly outdated! +You'll see output like: ``` -C:\users\username\> python -V -Python 2.7.18 +Searching for Python 3.14 +Installed Python 3.14.2 in 2.34s + + cpython-3.14.2-windows-x86_64-none ``` -If you have `Python 2.*`, then you are using an outdated version of Python. [**Since 2020, Python 2 has gone entirely unsupported**](https://stackoverflow.blog/2020/04/23/the-final-python-2-release-marks-the-end-of-an-era/) and should not be used. **You will need to continue below to install Python 3**. - -#### Ooops, you do NOT have Python +### Step 3. Verify It Works +```powershell +uv run python -V ``` -C:\users\username\> python -V -'python' is not recognized as a command or program. -``` - -Looks like you do not have Python at all. **You will need to continue below to install Python 3**. Note that the error message may be slightly different for **Windows Terminal**: *The term python is not recognized as a cmdlet, function, or operable program*. -#### Ooops, you still do NOT have Python +You should see: ``` -C:\users\username\> python -V -Python was not found; run without arguments to install from the Windows Store... +Python 3.14.2 ``` -Looks like you do not have Python at all. **You will need to continue below to install Python 3**. When you see this specific error message, it means that Python is not installed. What is running is a shim program meant to help you install Python 3 from the Windows Store (one option below). You can select this option by simplifying typing `python` and following along in the UI. - - -### Step 3. You need Python, install it on Windows - -So you need to install a new version of Python on your Windows machine. There are a variety of options for doing so. We'll run you through them, but **if you are uncertain which one to get, just use the official installer**. Keep in mind that no matter how you install Python, **you will likely need to close and reopen your terminal/command prompt for any changes to take effect**. - -- **Python Official Installer** << recommended -- Windows Store -- Chocolatey Package Manager for Windows -- Anaconda Distribution - -#### << **Python Official Installer on Windows** >> - -The Python official installer can be found on **[python.org](http://python.org)**. - -**Pros** - -* It's the primary way the Python Software Foundation delivers Python to users -* The installer is supported by core developers working at Microsoft - -**Cons** - -* You will not be notified of possible updates -* There is no mechanism to have a new version automatically replace the installed version - -**Install steps - Windows official installer**: - -1. Visit the **[downloads page for Windows at python.org](https://www.python.org/downloads/windows/)** -2. Find the section entitled **Stable Releases** -3. Download the MSI installer under the **Download Windows installer (64-bit)** link -4. Run the installer - **be sure to check the "add python to my path" option** -5. Close all terminal and command prompt windows -6. Run `python -V` in a new terminal window to verify you have Python now working - -#### << **Windows Store version of Python** >> - -The Windows Store version of Python is a good option. It's the easiest way to get Python on Windows without administrator permissions. But there are some drawbacks too. - -**Pros** - -* Easiest way to get Python on Windows **without administrator permissions** -* Will keep Python up-to-date automatically within a release version (3.10 updates but not 3.10->3.11) -* Maintained by the core developers who work at Microsoft - -**Cons** - -* Does have some minor permission restrictions that apply to all Windows Store apps which can affect your development options - -**Install steps - Microsoft Store Python**: - -1. Open the Microsoft Store on Windows -2. Search for Python -3. Find the latest version of Python from Microsoft (currently lists 3.7, 3.8, 3.9, 3.10, 3.11, and [**3.12**](https://apps.microsoft.com/detail/python-3-12/9NCVDN91XZQP?hl=en-us&gl=US)) -4. Install from the Microsoft Store -5. Close all terminal and command prompt windows -6. Run `python -V` in a new terminal window to verify you have Python now working - - -#### << **Chocolatey Package Manager for Windows** >> - -[Chocolatey](https://chocolatey.org/) is a [package manager](https://en.wikipedia.org/wiki/Package_manager): software tools that automates the process of installing, upgrading, configuring, and removing computer programs for a computer's operating system in a consistent manner. If you're comfortable using package managers, then this is a good option for you because you can continually update and maintain Python on your system. - -**Pros** - -* Will keep Python up-to-date on your system as long as you periodically run the upgrade command -* Will update across versions (e.g. 3.11 -> 3.12) -* Can inform you of pending upgrade if upgrade command is run - -**Cons** - -* Complex to use -* Must run as administrator -* Requires separate install of chocolatey itself - -**Install steps - Chocolatey package manager on Windows** - -1. Install Chocolatey - [**steps here**](https://docs.chocolatey.org/en-us/choco/setup) -2. Open an **[administrator command prompt](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/)** -3. Install the latest Python: `choco install python` -4. Periodically check for a new release: Open admin command prompt and run `choco upgrade python` -5. Close all terminal and command prompt windows and reopen one (to refresh the path) -6. Run `python -V` in a new terminal window to verify you have Python now working - - -#### << **Anaconda distribution on Windows** >> - -[Anaconda is a distribution of Python](https://www.anaconda.com/products/individual) that packages many of the common data science packages pre-configured for your system. It is a good option for data scientists. - -**Pros** - -* Many packages and libraries are pre-installed -* Good for data science tooling in Python - -**Cons** - -* Generally uses [conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) rather than [Python's virtual environments](https://www.geeksforgeeks.org/python-virtual-environment/) - this can lead to a mismatch in instructions when Anaconda is not the primary tool used. -* Packages available here often lag behind in release schedule from PyPI / pip -* Often one whole version behind on Python (e.g. 3.10 rather than 3.11) - -**Install steps - Anaconda distribution on Windows** - -1. [Download the Windows installer](https://www.anaconda.com/products/individual#) -2. Run the installer, add Python to path if asked -3. Close all terminal and command prompt windows -4. Run `python -V` in a new terminal window to verify you have Python now working - - - +**You're all set!** ๐ŸŽ‰ _________________________ ## macOS -### Step 2. Do you have Python? Let's check +### Step 1. Install uv -To determine if you have Python installed, open the [**terminal**](https://www.makeuseof.com/open-terminal-on-mac/). Verify you have Python: In the terminal, type **python3 -V** (capital V): +Open the [**Terminal**](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) and run: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -$ python3 -V -``` - -The output should be one of the following (*version numbers will vary*). Do not type **$** - macOS displays this as part of the terminal UI. -#### Success, you have Python +After installation completes, **close and reopen your terminal** for the changes to take effect. -``` -$ python3 -V -Python 3.12.0 -``` +### Step 2. Install Python -If you see this and the reported version number is sufficiently high (often 3.9 or higher), **you are good to go**. +Now install Python 3.14 with a single command: -#### 2.7? Uh oh, your Python is badly outdated! - -If `python3` **does NOT run successfully**, but `python` (without the 3) itself does and you see the output: - -``` -$ python -V -Python 2.7.18 +```bash +uv python install 3.14 ``` -If you have `Python 2.*`, then you are using an outdated version of Python. [**Since 2020, Python 2 has gone entirely unsupported**](https://stackoverflow.blog/2020/04/23/the-final-python-2-release-marks-the-end-of-an-era/) and should not be used. **You will need to continue below to install Python 3**. - -#### Ooops, you do NOT have Python +You'll see output like: ``` -$ python3 -V -bash: python3: command not found +Searching for Python 3.14 +Installed Python 3.14.2 in 1.89s + + cpython-3.14.2-macos-aarch64-none ``` -Looks like you do not have Python 3 at all. **You will need to continue below to install Python 3**. Note that the error message is slightly different for different shells. - - -### Step 3. You need Python, install it on macOS - -- **Homebrew** << recommended -- Python Official Installer -- Anaconda distribution - - -#### << **Homebrew Package Manager for macOS** >> - -**[Homebrew](https://brew.sh/)** is a [package manager](https://en.wikipedia.org/wiki/Package_manager): software tools that automates the process of installing, upgrading, configuring, and removing computer programs for a computer's operating system in a consistent manner. If you're comfortable using package managers, then this is a good option for you because you can continually update and maintain Python on your system. - -**Pros** - -* Will keep Python up-to-date on your system as long as you periodically run the upgrade command -* Will update across versions (e.g. 3.11 -> 3.12) -* Can inform you of pending upgrade if upgrade command is run - -**Cons** - -* Complex to use -* Requires separate install of homebrew itself - -**Install steps - Homebrew package manager on macOS** - -1. Install Homebrew - [**steps here**](https://brew.sh/) -2. Open a **[terminal](https://www.makeuseof.com/open-terminal-on-mac/)** -3. Install the latest Python: `brew install python` -4. Periodically check for a new release: Open terminal and run `brew update` then `brew upgrade` -5. **CAREFUL**: Take careful note of any messages shown - sometimes you must [update your path](https://coolestguidesontheplanet.com/add-shell-path-osx/) (varies by default shell: bash, zsh, etc.) for this version to be located. -5. Close all terminal windows -6. Run `python3 -V` in a new terminal window to verify you have Python now working - - -#### << **Python Official Installer on macOS** >> - -The Python official installer can be found on **[python.org](http://python.org)**. - -**Pros** - -* It's the primary way the Python Software Foundation delivers Python to users -* The installer is supported by core developers - -**Cons** - -* You will not be notified of possible updates -* There is no mechanism to have a new version automatically replace the installed version -* Requires admin permissions - -**Install steps - macOS official installer**: - -1. Visit the **[downloads page for macOS](https://www.python.org/downloads/mac-osx/)** -2. Find the section entitled **Stable Releases** -3. Download the PKG installer under the **Download macOS 64-bit universal2 installer** link -4. Run the installer -5. Close all terminal and command prompt windows -6. Run `python3 -V` in a new terminal window to verify you have Python now working - - -#### << **Anaconda distribution on macOS** >> - -[Anaconda is a distribution of Python](https://www.anaconda.com/products/individual) that packages many of the common data science packages pre-configured for your system. It is a good option for data scientists. - -**Pros** - -* Many packages and libraries are pre-installed -* Good for data science tooling in Python - -**Cons** - -* Generally uses [conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) rather than [Python's virtual environments](https://www.geeksforgeeks.org/python-virtual-environment/) - this can lead to a mismatch in instructions when Anaconda is not the primary tool used. -* Packages available here often lag behind in release schedule from PyPI / pip -* Often one whole version behind on Python (e.g. 3.11 rather than 3.12) +### Step 3. Verify It Works -**Install steps - Anaconda distribution on Windows** - -1. [Download the macOS installer](https://www.anaconda.com/products/individual#) -2. Run the installer, add Python to path if asked -3. Close all terminal and command prompt windows -4. Run `python3 -V` in a new terminal window to verify you have Python now working +```bash +python -V +# or +uv run python -V +``` +You should see: +``` +Python 3.14.2 +``` +**You're all set!** ๐ŸŽ‰ _________________________ ## Linux -### Step 2. Do you have Python? Let's check - -To determine if you have Python installed, open the [**terminal**](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/). Verify you have Python, in the terminal, type **python3 -V** (capital V): - -``` -$ python3 -V -``` - -The output should be one of the following (*version numbers will vary*). Don't type **$** - Linux displays this as part of the terminal UI. +### Step 1. Install uv -#### Success, you have Python +Open a [**terminal**](https://ubuntu.com/tutorials/command-line-for-beginners) and run: -``` -$ python3 -V -Python 3.12.0 +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -If you see this and the reported version number is sufficiently high (often 3.10 or higher), **you are good to go**. +After installation completes, **close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`) for the changes to take effect. -#### 2.7? Uh oh, your Python is badly outdated! +### Step 2. Install Python -If `python3` **does NOT run successfully**, but `python` (without the 3) itself does and you see the output: +Now install Python 3.14 with a single command: -``` -$ python -V -Python 2.7.18 +```bash +uv python install 3.14 ``` -If you have `Python 2.*`, then you are using an outdated version of Python. [**Since 2020, Python 2 has gone entirely unsupported**](https://stackoverflow.blog/2020/04/23/the-final-python-2-release-marks-the-end-of-an-era/) and should not be used. **You will need to continue below to install Python 3**. - -#### Ooops, you do NOT have Python +You'll see output like: ``` -$ python3 -V -bash: python3: command not found +Searching for Python 3.14 +Installed Python 3.14.2 in 1.52s + + cpython-3.14.2-linux-x86_64-gnu ``` -Looks like you do not have Python 3 at all. **You will need to continue below to install Python 3**. Note that the error message is slightly different for different shells. - +### Step 3. Verify It Works -### Step 3. You need Python, install it on Linux +```bash +python -V -- **Package manager** << recommended -- Anaconda -- Compiled from source +# or -Note that **these instructions are for Ubuntu**. With the many variants of Linux, you many need to adjust slightly (e.g. yum vs. apt) +uv run python -V +``` +You should see: -#### << **Built-in Package Manager for Ubuntu** >> +``` +Python 3.14.2 +``` -Ubuntu manages it's installed software using **[apt](https://ubuntu.com/server/docs/package-management)**. This is a good way to install and manage Python 3 on your system. +**You're all set!** ๐ŸŽ‰ -**Pros** +_________________________ -* Will keep Python up-to-date on your system as long as you periodically run the upgrade command -* Will update across versions (e.g. 3.11 -> 3.12) -* Can inform you of pending upgrade if upgrade command is run +## Working with Python Projects -**Cons** +Once you have uv installed, you'll typically work within **virtual environments** for your projects. uv makes this simple: -* Requires root permissions -* Often lags badly behind the latest version (sometimes about 1.5 years behind) +### Creating a Virtual Environment -**Install steps - apt package manager on Ubuntu** +Navigate to your project folder and run: -1. Open a **[terminal](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/)** -2. Update the package sources: `sudo apt update` -3. Upgrade currently installed software: `sudo apt upgrade` -4. Install the latest Python 3: `sudo apt install build-essential libssl-dev libffi-dev python3-dev` -4. Make sure we have pip as part of our Python: `sudo apt install python3-pip` -5. Close all terminal windows -6. Run `python3 -V` in a new terminal window to verify you have Python now working +```bash +uv venv --python 3.14 +``` +This creates a `.venv` folder in your project. If Python 3.14 isn't already installed, **uv will automatically download and install it for you**. +### Activating the Virtual Environment -#### << **Anaconda distribution on Ubuntu** >> +**Windows (PowerShell):** +```powershell +.venv\Scripts\Activate.ps1 +``` -[Anaconda is a distribution of Python](https://www.anaconda.com/products/individual) that packages many of the common data science packages pre-configured for your system. It is a good option for data scientists. +**macOS / Linux:** +```bash +source .venv/bin/activate +``` -**Pros** +Once activated, you can use `python` directly: -* Many packages and libraries are pre-installed -* Good for data science tooling in Python +```bash +python -V +``` -**Cons** +### Installing Packages -* Generally uses [conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) rather than [Python's virtual environments](https://www.geeksforgeeks.org/python-virtual-environment/) - this can lead to a mismatch in instructions when Anaconda is not the primary tool used. -* Packages available here often lag behind in release schedule from PyPI / pip -* Often one whole version behind on Python (e.g. 3.11 rather than 3.12) +With uv, installing packages is lightning fast: -**Install steps - Anaconda distribution on Ubuntu** +```bash +uv pip install requests +``` -1. [Download the Linux installer](https://www.anaconda.com/products/individual#) -2. Run the installer, add Python to path if asked -3. Close all terminal and command prompt windows -4. Run `python3 -V` in a new terminal window to verify you have Python now working +Or add dependencies to a project: +```bash +uv add requests +``` +_________________________ +## Managing Multiple Python Versions -#### << **Building python from source on Ubuntu** >> +Need multiple Python versions? uv handles that too: -While we would not generally recommend building Python 3 from source, if you need the very latest on your system, often this is one of the few options available. +```bash +uv python install 3.12 3.13 3.14 +``` -**Pros** +List installed versions: -* You'll have the very latest Python you've gotten from source (potentially even pre-release versions) +```bash +uv python list +``` -**Cons** +Create a virtual environment with a specific version: -* Complicated and fraught with pitfalls -* Can require root permissions for additional build libraries +```bash +uv venv --python 3.12 +``` +_________________________ -**Install steps - Building python from source on Ubuntu** +## Why uv? -1. Open a **[terminal](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/)** -2. Ensure your package listings and software are up-to-date: `sudo apt-get update` -3. Install the build tools: `sudo apt-get install -y build-essential checkinstall` -4. Add additional libraries needed by Python to build: `apt-get install libreadline-gplv2-dev libncursesw5-dev libssl-dev libffi-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev` -5. Change into the src directory: `cd /usr/src` -6. Get the latest source from [python.org/downloads/source](https://www.python.org/downloads/source/) and wget it locally, e.g.: `sudo wget https://www.python.org/ftp/python/3.12.0/Python-3.12.0.tgz` -7. Decompress it (varies by version): `sudo tar xzf Python-3.12.0.tgz` -8. Change into the created directory (varies by version): `cd Python-3.12.0` -9. Prepare it for compilation: `sudo ./configure --enable-optimizations` -10. Compile it without modifying system Python: `sudo make altinstall` -11. Verify this version was built (varies by version): `python3.12 --version` -12. Use `python3.12` instead of `python` or `python3` commands -13. Consider creating an [alias](https://www.howtogeek.com/73768/how-to-use-aliases-to-customize-ubuntu-commands/) of `python3.12` to `python` in your shell profile. +**[uv](https://docs.astral.sh/uv/)** is developed by [Astral](https://astral.sh/), the creators of [Ruff](https://docs.astral.sh/ruff/) (the popular Python linter). It's designed to be: -There is a [nice write up of this procedure over here](https://towardsdatascience.com/building-python-from-source-on-ubuntu-20-04-2ed29eec152b). +- โšก๏ธ **Blazing fast** -- 10-100x faster than pip +- ๐Ÿ **Python version manager** -- installs and manages Python itself +- ๐Ÿ“ฆ **Package manager** -- replaces pip, pip-tools, and virtualenv +- ๐Ÿ”’ **Lockfile support** -- reproducible environments +- ๐Ÿ–ฅ๏ธ **Cross-platform** -- works identically on Windows, macOS, and Linux +One tool. No complexity. Just Python. ------------------------------- -## Corrections and improvements +## Corrections and Improvements If you find a problem or have a suggestion to make this page better, please visit the GitHub repository here. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions: From 132958bfdf0e768a11b205b038c9f459b3550a56 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Wed, 10 Dec 2025 16:50:18 -0800 Subject: [PATCH 3/8] add change log for future updates. --- change-log.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 change-log.md diff --git a/change-log.md b/change-log.md new file mode 100644 index 0000000..d9f5b6a --- /dev/null +++ b/change-log.md @@ -0,0 +1,38 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +## [2025.12.10] - python-2025-guide + +### Changed +- **Completely modernized Python installation guide for 2025** + - Replaced 10 different installation methods with unified uv approach + - Simplified guide from 454 lines to ~256 lines + - Updated target Python version from 3.12 to 3.14.2 + - Guide now works identically across Windows, macOS, and Linux + +### Added +- Installation instructions using uv (one-command install per platform) +- Section on working with Python projects and virtual environments +- Section on managing multiple Python versions with uv +- "Why uv?" explanation section +- Link to Talk Python episode #476 about unified Python packaging with uv + +### Removed +- Anaconda distribution installation instructions +- Chocolatey package manager for Windows +- Homebrew package manager for macOS +- Windows Store Python installation +- Official python.org installer instructions +- Building Python from source on Linux +- All pros/cons decision-making complexity +- Python 2.7 outdated version warnings (it's 2025!) + +## Previous Versions + +The guide existed prior to this changelog. This represents the first tracked release using the modernized uv-based approach. + From 3adbd96346eeaed3f36b1101cd434b9d52970399 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Thu, 16 Jul 2026 21:33:04 -0700 Subject: [PATCH 4/8] Fix python -V verification, install Python with --default uv python install only creates a versioned python3.14 executable, so the macOS and Linux verification steps told readers to run `python -V` and expect success when they would actually hit "command not found" -- right at the guide's "You're all set!" line. Install with --default on all three platforms, which creates the python and python3 executables the guide promises, and drop the `uv run python -V` workaround that was papering over this on Windows. Verified against uv 0.11.29: a clean install now yields python -V -> Python 3.14.6 on all platforms. Also: - Correct sample output; uv prints no "Searching for Python 3.14" line and lists the installed executables - Update 3.14.2 -> 3.14.6, note patch version and timing will vary, and resolve the "3.12+ recommended" vs installing 3.14 contradiction - Rewrite venv activation to teach isolation rather than availability, since --default makes "you can use python directly" a non-statement - Warn that --default repoints python when installing multiple versions - Fix two silently-ignored .rumdl.toml keys: disabled-rules -> disable and MD048.code-fence-style -> MD048.style, which is why intentional inline HTML was flagged on every run - Refresh README's stale "complex decision tree" framing --- .rumdl.toml | 4 +- README.md | 6 +-- change-log.md | 15 ++++++++ install-python.md | 93 ++++++++++++++++++++++++++++++----------------- 4 files changed, 79 insertions(+), 39 deletions(-) diff --git a/.rumdl.toml b/.rumdl.toml index 5cec1d1..aff4e86 100644 --- a/.rumdl.toml +++ b/.rumdl.toml @@ -4,7 +4,7 @@ exclude = ["node_modules", "build", "dist"] respect-gitignore = true # Disable specific rules -disabled-rules = ["MD013", "MD033"] +disable = ["MD013", "MD033"] # Configure individual rules [MD007] @@ -23,4 +23,4 @@ tables = false names = ["rumdl", "Markdown", "GitHub"] [MD048] -code-fence-style = "backtick" \ No newline at end of file +style = "backtick" \ No newline at end of file diff --git a/README.md b/README.md index 5bdc976..0cf39bf 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Installing Python -Installing Python always seems to be some complex decision tree experiment. Do you have Windows or macOS? Is Python already installed? Is it the right version? And so on. +Installing Python used to be a complex decision tree experiment. Windows, macOS, or Linux? Is Python already installed? Is it the right version? Anaconda, Homebrew, or python.org? Not anymore โ€” these days it's two commands on every platform, thanks to [uv](https://docs.astral.sh/uv/). This repo is a place to allow for feedback and conversations around our **[Installing Python from Talk Python Training how-to article](https://training.talkpython.fm/installing-python)**. -See the article source via [`install-python.md`](./install-python.md). +See the article source via [`install-python.md`](./install-python.md), and notable changes in [`change-log.md`](./change-log.md). -Post an issue if you have a problem or comment *with the article* - note that we can't do tech support in general for you. If you have a fix, PRs are accepted if they are a good fit. \ No newline at end of file +Post an issue if you have a problem or comment *with the article* โ€” note that we generally can't provide tech support. If you have a fix, PRs are accepted if they are a good fit. diff --git a/change-log.md b/change-log.md index d9f5b6a..59de4ab 100644 --- a/change-log.md +++ b/change-log.md @@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +### Fixed +- **`python -V` now actually works after following the guide.** `uv python install 3.14` only creates a versioned `python3.14` executable, so the macOS and Linux verification steps told readers to run `python -V` and expect success when they'd get `command not found`. All three platforms now install with `--default`, which creates the `python` and `python3` executables the guide promises. +- Verification step is now consistent across Windows, macOS, and Linux (previously Windows used `uv run python -V` while macOS and Linux claimed bare `python -V` worked). +- Corrected sample command output, which showed a `Searching for Python 3.14` line that uv does not print and omitted the installed executable names. +- Updated Python version references from 3.14.2 to 3.14.6, and resolved the intro contradiction between "3.12+ is recommended" and installing 3.14. +- Rewrote the virtual environment explanation. It said "once activated, you can use `python` directly," which was only meaningful back when bare `python` didn't work at all. It now teaches what activation actually does: `python` switches from your global 3.14 to the project's interpreter, which may be a different version entirely. +- Refreshed the README, which still described the guide as a "complex decision tree" โ€” the exact thing the 2025 rewrite eliminated. Also added Linux (the guide covers it), linked the changelog, and fixed punctuation. +- Fixed two silently-ignored keys in `.rumdl.toml`: `disabled-rules` โ†’ `disable` and `MD048.code-fence-style` โ†’ `MD048.style`. Because the disable list never loaded, the guide's intentional inline HTML was being flagged on every run. + +### Added +- Note that `--default` emits an experimental warning, so readers don't think the install failed. +- Note that the patch version and install time in sample output will differ, so the page doesn't read as wrong the moment 3.14.7 ships. +- Warning against using `--default` when installing multiple Python versions, plus how to intentionally repoint `python` at a different version later. +- Explicit "close and reopen your terminal" reminder in each verification step. + ## [2025.12.10] - python-2025-guide ### Changed diff --git a/install-python.md b/install-python.md index 73f32e5..dfbe121 100644 --- a/install-python.md +++ b/install-python.md @@ -2,9 +2,9 @@ -Welcome soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.12+ is recommended these days). +Welcome soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below). -Good news! In 2025, installing Python has become incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)** -- a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python. +Good news! These days, installing Python has become incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)** -- a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python. ## The Modern Approach: Install uv, Then Python @@ -39,27 +39,32 @@ After installation completes, **close and reopen your terminal** for the changes Now install Python 3.14 with a single command: ```powershell -uv python install 3.14 +uv python install 3.14 --default ``` +The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. + You'll see output like: -``` -Searching for Python 3.14 -Installed Python 3.14.2 in 2.34s - + cpython-3.14.2-windows-x86_64-none +```text +Installed Python 3.14.6 in 2.1s + + cpython-3.14.6-windows-x86_64-none (python, python3, python3.14) ``` +Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. + ### Step 3. Verify It Works +**Close and reopen your terminal**, then run: + ```powershell -uv run python -V +python -V ``` You should see: -``` -Python 3.14.2 +```text +Python 3.14.6 ``` **You're all set!** ๐ŸŽ‰ @@ -84,31 +89,32 @@ After installation completes, **close and reopen your terminal** for the changes Now install Python 3.14 with a single command: ```bash -uv python install 3.14 +uv python install 3.14 --default ``` +The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. + You'll see output like: -``` -Searching for Python 3.14 -Installed Python 3.14.2 in 1.89s - + cpython-3.14.2-macos-aarch64-none +```text +Installed Python 3.14.6 in 1.9s + + cpython-3.14.6-macos-aarch64-none (python, python3, python3.14) ``` +Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. + ### Step 3. Verify It Works +**Close and reopen your terminal**, then run: + ```bash python -V - -# or - -uv run python -V ``` You should see: -``` -Python 3.14.2 +```text +Python 3.14.6 ``` **You're all set!** ๐ŸŽ‰ @@ -133,31 +139,32 @@ After installation completes, **close and reopen your terminal** (or run `source Now install Python 3.14 with a single command: ```bash -uv python install 3.14 +uv python install 3.14 --default ``` +The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. + You'll see output like: +```text +Installed Python 3.14.6 in 1.5s + + cpython-3.14.6-linux-x86_64-gnu (python, python3, python3.14) ``` -Searching for Python 3.14 -Installed Python 3.14.2 in 1.52s - + cpython-3.14.2-linux-x86_64-gnu -``` + +Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. ### Step 3. Verify It Works +**Close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`), then run: + ```bash python -V - -# or - -uv run python -V ``` You should see: -``` -Python 3.14.2 +```text +Python 3.14.6 ``` **You're all set!** ๐ŸŽ‰ @@ -181,21 +188,31 @@ This creates a `.venv` folder in your project. If Python 3.14 isn't already inst ### Activating the Virtual Environment **Windows (PowerShell):** + ```powershell .venv\Scripts\Activate.ps1 ``` **macOS / Linux:** + ```bash source .venv/bin/activate ``` -Once activated, you can use `python` directly: +Activating doesn't just make `python` available โ€” it changes which Python `python` means. Instead of the global 3.14 you installed earlier, it now points at this project's interpreter, which can be an entirely different version: ```bash python -V ``` +In a project created with `uv venv --python 3.12`, that reports: + +```text +Python 3.12.13 +``` + +When you're finished working on the project, run `deactivate` and `python` goes back to your global 3.14. + ### Installing Packages With uv, installing packages is lightning fast: @@ -220,7 +237,9 @@ Need multiple Python versions? uv handles that too: uv python install 3.12 3.13 3.14 ``` -List installed versions: +Note there's no `--default` here. Only one version at a time can own the plain `python` command, so leave `--default` off when installing extra versions โ€” otherwise you'll quietly repoint `python` at whichever version you installed last. Each version is always reachable by its full name (`python3.12`, `python3.13`) regardless. + +List installed versions, including any that came with your system: ```bash uv python list @@ -232,6 +251,12 @@ Create a virtual environment with a specific version: uv venv --python 3.12 ``` +Want to move `python` to a different version later? Re-run the install with `--default`: + +```bash +uv python install 3.13 --default +``` + _________________________ ## Why uv? From 0975e4210d9ef9d5acbd24d2a955cf2402504a35 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Thu, 16 Jul 2026 21:36:18 -0700 Subject: [PATCH 5/8] Apply rumdl fmt, fix MD044 rewriting the repo URL Formatting only: list markers to '-', blank lines before the horizontal rules following the HTML anchors, blank lines after changelog headings, and a consistent horizontal rule style. One non-cosmetic fix: MD044's proper-names rule was rewriting the link text "https://github.com/..." to "https://GitHub.com/...", so the page would render a capitalized URL on every fmt run. The link text is now descriptive rather than a raw URL, which sidesteps the rule and also drops the dangling "visit the GitHub repository here". --- change-log.md | 8 ++++++-- install-python.md | 15 +++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/change-log.md b/change-log.md index 59de4ab..0585899 100644 --- a/change-log.md +++ b/change-log.md @@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] ### Fixed + - **`python -V` now actually works after following the guide.** `uv python install 3.14` only creates a versioned `python3.14` executable, so the macOS and Linux verification steps told readers to run `python -V` and expect success when they'd get `command not found`. All three platforms now install with `--default`, which creates the `python` and `python3` executables the guide promises. - Verification step is now consistent across Windows, macOS, and Linux (previously Windows used `uv run python -V` while macOS and Linux claimed bare `python -V` worked). - Corrected sample command output, which showed a `Searching for Python 3.14` line that uv does not print and omitted the installed executable names. @@ -16,6 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Fixed two silently-ignored keys in `.rumdl.toml`: `disabled-rules` โ†’ `disable` and `MD048.code-fence-style` โ†’ `MD048.style`. Because the disable list never loaded, the guide's intentional inline HTML was being flagged on every run. ### Added + - Note that `--default` emits an experimental warning, so readers don't think the install failed. - Note that the patch version and install time in sample output will differ, so the page doesn't read as wrong the moment 3.14.7 ships. - Warning against using `--default` when installing multiple Python versions, plus how to intentionally repoint `python` at a different version later. @@ -24,13 +26,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [2025.12.10] - python-2025-guide ### Changed + - **Completely modernized Python installation guide for 2025** - Replaced 10 different installation methods with unified uv approach - Simplified guide from 454 lines to ~256 lines - Updated target Python version from 3.12 to 3.14.2 - Guide now works identically across Windows, macOS, and Linux - + ### Added + - Installation instructions using uv (one-command install per platform) - Section on working with Python projects and virtual environments - Section on managing multiple Python versions with uv @@ -38,6 +42,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Link to Talk Python episode #476 about unified Python packaging with uv ### Removed + - Anaconda distribution installation instructions - Chocolatey package manager for Windows - Homebrew package manager for macOS @@ -50,4 +55,3 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## Previous Versions The guide existed prior to this changelog. This represents the first tracked release using the modernized uv-based approach. - diff --git a/install-python.md b/install-python.md index dfbe121..85b8b96 100644 --- a/install-python.md +++ b/install-python.md @@ -15,11 +15,12 @@ The process is just two steps: That's it! Jump to your operating system to get started: -* [**Windows**](#windows) -* [**macOS**](#macos) -* [**Linux**](#linux) +- [**Windows**](#windows) +- [**macOS**](#macos) +- [**Linux**](#linux) + _________________________ ## Windows @@ -70,6 +71,7 @@ Python 3.14.6 **You're all set!** ๐ŸŽ‰ + _________________________ ## macOS @@ -120,6 +122,7 @@ Python 3.14.6 **You're all set!** ๐ŸŽ‰ + _________________________ ## Linux @@ -271,10 +274,10 @@ _________________________ One tool. No complexity. Just Python. -------------------------------- +_________________________ ## Corrections and Improvements -If you find a problem or have a suggestion to make this page better, please visit the GitHub repository here. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions: +If you find a problem or have a suggestion to make this page better, please open an issue on GitHub. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions: -[**https://github.com/talkpython/installing-python**](https://github.com/talkpython/installing-python) +[**talkpython/installing-python**](https://github.com/talkpython/installing-python) From 5fd6f58eeccf2b5212d256554d7daa981d5f86c0 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Thu, 16 Jul 2026 21:53:34 -0700 Subject: [PATCH 6/8] Cut 2026.07.16 release, prose and dash pass Move the Unreleased entries into a dated release matching the existing YYYY.MM.DD - slug convention, and leave Unreleased empty for next time. Prose: - Replace em dashes with plain hyphens or shorter sentences across the guide and README, keeping dashes where they earn their place - Tighten the --default explanation, which used "default" three times - Fix a comma splice in the experimental-warning note - "which interpreter python points to" rather than tangling Python/python Step 3 no longer opens by telling readers to close and reopen a terminal they already reopened in Step 1. Once ~/.local/bin is on PATH, python resolves as soon as the install finishes (verified with an isolated PATH), so the reopen is now a fallback after the expected output, where someone who actually needs it will look. Two changelog entries were stale: one claimed we added the reopen reminder we ended up removing, and the fmt/MD044 work was unrecorded. --- README.md | 4 ++-- change-log.md | 12 ++++++++++-- install-python.md | 48 +++++++++++++++++++++++------------------------ 3 files changed, 36 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 0cf39bf..571ca31 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Installing Python -Installing Python used to be a complex decision tree experiment. Windows, macOS, or Linux? Is Python already installed? Is it the right version? Anaconda, Homebrew, or python.org? Not anymore โ€” these days it's two commands on every platform, thanks to [uv](https://docs.astral.sh/uv/). +Installing Python used to be a complex decision tree experiment. Windows, macOS, or Linux? Is Python already installed? Is it the right version? Anaconda, Homebrew, or python.org? Not anymore. These days it's two commands on every platform, thanks to [uv](https://docs.astral.sh/uv/). This repo is a place to allow for feedback and conversations around our **[Installing Python from Talk Python Training how-to article](https://training.talkpython.fm/installing-python)**. See the article source via [`install-python.md`](./install-python.md), and notable changes in [`change-log.md`](./change-log.md). -Post an issue if you have a problem or comment *with the article* โ€” note that we generally can't provide tech support. If you have a fix, PRs are accepted if they are a good fit. +Post an issue if you have a problem or comment *with the article*. Note that we generally can't provide tech support. If you have a fix, PRs are accepted if they are a good fit. diff --git a/change-log.md b/change-log.md index 0585899..d6f8268 100644 --- a/change-log.md +++ b/change-log.md @@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [2026.07.16] - python-default-flag + ### Fixed - **`python -V` now actually works after following the guide.** `uv python install 3.14` only creates a versioned `python3.14` executable, so the macOS and Linux verification steps told readers to run `python -V` and expect success when they'd get `command not found`. All three platforms now install with `--default`, which creates the `python` and `python3` executables the guide promises. @@ -13,15 +15,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Corrected sample command output, which showed a `Searching for Python 3.14` line that uv does not print and omitted the installed executable names. - Updated Python version references from 3.14.2 to 3.14.6, and resolved the intro contradiction between "3.12+ is recommended" and installing 3.14. - Rewrote the virtual environment explanation. It said "once activated, you can use `python` directly," which was only meaningful back when bare `python` didn't work at all. It now teaches what activation actually does: `python` switches from your global 3.14 to the project's interpreter, which may be a different version entirely. -- Refreshed the README, which still described the guide as a "complex decision tree" โ€” the exact thing the 2025 rewrite eliminated. Also added Linux (the guide covers it), linked the changelog, and fixed punctuation. +- Refreshed the README, which still described the guide as a "complex decision tree". That's the exact thing the 2025 rewrite eliminated. Also added Linux (the guide covers it), linked the changelog, and fixed punctuation. - Fixed two silently-ignored keys in `.rumdl.toml`: `disabled-rules` โ†’ `disable` and `MD048.code-fence-style` โ†’ `MD048.style`. Because the disable list never loaded, the guide's intentional inline HTML was being flagged on every run. +- Stopped `rumdl fmt` from rewriting the repo link to display `https://GitHub.com/...`. MD044's proper-name rule was capitalizing the URL in the link text on every run. The link text is now descriptive rather than a raw URL. ### Added - Note that `--default` emits an experimental warning, so readers don't think the install failed. - Note that the patch version and install time in sample output will differ, so the page doesn't read as wrong the moment 3.14.7 ships. - Warning against using `--default` when installing multiple Python versions, plus how to intentionally repoint `python` at a different version later. -- Explicit "close and reopen your terminal" reminder in each verification step. +- `PATH` troubleshooting fallback in each verification step, phrased per platform, for anyone whose terminal hasn't picked up the new executables. + +### Changed + +- Prose pass over the guide and README: replaced em dashes with plain hyphens or shorter sentences, tightened the `--default` explanation, and corrected the "two steps" promise that was followed by three. +- Applied `rumdl fmt` for consistent list markers, horizontal rules, and blank lines. ## [2025.12.10] - python-2025-guide diff --git a/install-python.md b/install-python.md index 85b8b96..c59a174 100644 --- a/install-python.md +++ b/install-python.md @@ -2,13 +2,13 @@ -Welcome soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below). +Welcome, soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below). -Good news! These days, installing Python has become incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)** -- a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python. +The good news is that these days, installing Python is incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)**, a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python. ## The Modern Approach: Install uv, Then Python -The process is just two steps: +The process is just two commands: 1. **Install uv** (one command) 2. **Install Python with uv** (one command) @@ -43,7 +43,7 @@ Now install Python 3.14 with a single command: uv python install 3.14 --default ``` -The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. +The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on. You'll see output like: @@ -52,12 +52,10 @@ Installed Python 3.14.6 in 2.1s + cpython-3.14.6-windows-x86_64-none (python, python3, python3.14) ``` -Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. +Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. ### Step 3. Verify It Works -**Close and reopen your terminal**, then run: - ```powershell python -V ``` @@ -68,6 +66,8 @@ You should see: Python 3.14.6 ``` +If PowerShell says `python` isn't recognized, close and reopen your terminal so it picks up the updated `PATH`, then try again. + **You're all set!** ๐ŸŽ‰ @@ -94,7 +94,7 @@ Now install Python 3.14 with a single command: uv python install 3.14 --default ``` -The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. +The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on. You'll see output like: @@ -103,12 +103,10 @@ Installed Python 3.14.6 in 1.9s + cpython-3.14.6-macos-aarch64-none (python, python3, python3.14) ``` -Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. +Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. ### Step 3. Verify It Works -**Close and reopen your terminal**, then run: - ```bash python -V ``` @@ -119,6 +117,8 @@ You should see: Python 3.14.6 ``` +If you get a `command not found` error, close and reopen your terminal so it picks up the updated `PATH`, then try again. + **You're all set!** ๐ŸŽ‰ @@ -145,7 +145,7 @@ Now install Python 3.14 with a single command: uv python install 3.14 --default ``` -The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on. +The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on. You'll see output like: @@ -154,12 +154,10 @@ Installed Python 3.14.6 in 1.5s + cpython-3.14.6-linux-x86_64-gnu (python, python3, python3.14) ``` -Your exact patch version and install time will differ โ€” Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet. +Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. ### Step 3. Verify It Works -**Close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`), then run: - ```bash python -V ``` @@ -170,6 +168,8 @@ You should see: Python 3.14.6 ``` +If you get a `command not found` error, close and reopen your terminal (or run `source ~/.bashrc` or `source ~/.zshrc`) so it picks up the updated `PATH`, then try again. + **You're all set!** ๐ŸŽ‰ _________________________ @@ -186,7 +186,7 @@ Navigate to your project folder and run: uv venv --python 3.14 ``` -This creates a `.venv` folder in your project. If Python 3.14 isn't already installed, **uv will automatically download and install it for you**. +This creates a `.venv` folder in your project. If Python 3.14 isn't already installed, **uv will automatically download and install it for you**. On a fast connection, this can take as little as 2-3 seconds. ### Activating the Virtual Environment @@ -202,7 +202,7 @@ This creates a `.venv` folder in your project. If Python 3.14 isn't already inst source .venv/bin/activate ``` -Activating doesn't just make `python` available โ€” it changes which Python `python` means. Instead of the global 3.14 you installed earlier, it now points at this project's interpreter, which can be an entirely different version: +Activating doesn't just make `python` available - it changes which interpreter `python` points to. Instead of the global 3.14 you installed earlier, you get this project's own Python, which can be an entirely different version: ```bash python -V @@ -240,7 +240,7 @@ Need multiple Python versions? uv handles that too: uv python install 3.12 3.13 3.14 ``` -Note there's no `--default` here. Only one version at a time can own the plain `python` command, so leave `--default` off when installing extra versions โ€” otherwise you'll quietly repoint `python` at whichever version you installed last. Each version is always reachable by its full name (`python3.12`, `python3.13`) regardless. +Note there's no `--default` here. Only one version at a time can own the plain `python` command, so leave `--default` off when installing extra versions. Otherwise you'll quietly repoint `python` at whichever version you installed last. Each version is always reachable by its full name (`python3.12`, `python3.13`) regardless. List installed versions, including any that came with your system: @@ -266,11 +266,11 @@ _________________________ **[uv](https://docs.astral.sh/uv/)** is developed by [Astral](https://astral.sh/), the creators of [Ruff](https://docs.astral.sh/ruff/) (the popular Python linter). It's designed to be: -- โšก๏ธ **Blazing fast** -- 10-100x faster than pip -- ๐Ÿ **Python version manager** -- installs and manages Python itself -- ๐Ÿ“ฆ **Package manager** -- replaces pip, pip-tools, and virtualenv -- ๐Ÿ”’ **Lockfile support** -- reproducible environments -- ๐Ÿ–ฅ๏ธ **Cross-platform** -- works identically on Windows, macOS, and Linux +- โšก๏ธ **Blazing fast** - 10-100x faster than pip +- ๐Ÿ **Python version manager** - installs and manages Python itself +- ๐Ÿ“ฆ **Package manager** - replaces pip, pip-tools, and virtualenv +- ๐Ÿ”’ **Lockfile support** - reproducible environments +- ๐Ÿ–ฅ๏ธ **Cross-platform** - works identically on Windows, macOS, and Linux One tool. No complexity. Just Python. @@ -280,4 +280,4 @@ _________________________ If you find a problem or have a suggestion to make this page better, please open an issue on GitHub. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions: -[**talkpython/installing-python**](https://github.com/talkpython/installing-python) +[**https://github.com/talkpython/installing-python**](https://github.com/talkpython/installing-python) From 6896abf4f5339a32fc7657b7d486f1252af448be Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Thu, 16 Jul 2026 22:28:11 -0700 Subject: [PATCH 7/8] Fix formatting. --- install-python.md | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/install-python.md b/install-python.md index c59a174..0b018c8 100644 --- a/install-python.md +++ b/install-python.md @@ -1,6 +1,6 @@ -# Installing Python 3 +# How to Install Python 3.14 with uv - + Welcome, soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below). @@ -17,11 +17,9 @@ That's it! Jump to your operating system to get started: - [**Windows**](#windows) - [**macOS**](#macos) -- [**Linux**](#linux) +- [**Linux**](#linux) - - -_________________________ +
## Windows @@ -68,11 +66,8 @@ Python 3.14.6 If PowerShell says `python` isn't recognized, close and reopen your terminal so it picks up the updated `PATH`, then try again. -**You're all set!** ๐ŸŽ‰ - - - -_________________________ +**You're all set!** ๐ŸŽ‰ +
## macOS @@ -119,10 +114,7 @@ Python 3.14.6 If you get a `command not found` error, close and reopen your terminal so it picks up the updated `PATH`, then try again. -**You're all set!** ๐ŸŽ‰ - - - +**You're all set!** ๐ŸŽ‰ _________________________ ## Linux @@ -171,7 +163,6 @@ Python 3.14.6 If you get a `command not found` error, close and reopen your terminal (or run `source ~/.bashrc` or `source ~/.zshrc`) so it picks up the updated `PATH`, then try again. **You're all set!** ๐ŸŽ‰ - _________________________ ## Working with Python Projects @@ -229,7 +220,6 @@ Or add dependencies to a project: ```bash uv add requests ``` - _________________________ ## Managing Multiple Python Versions @@ -259,7 +249,6 @@ Want to move `python` to a different version later? Re-run the install with `--d ```bash uv python install 3.13 --default ``` - _________________________ ## Why uv? @@ -273,7 +262,6 @@ _________________________ - ๐Ÿ–ฅ๏ธ **Cross-platform** - works identically on Windows, macOS, and Linux One tool. No complexity. Just Python. - _________________________ ## Corrections and Improvements @@ -281,3 +269,8 @@ _________________________ If you find a problem or have a suggestion to make this page better, please open an issue on GitHub. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions: [**https://github.com/talkpython/installing-python**](https://github.com/talkpython/installing-python) + + From 80e48bd2f6b786cac969dfd9e42a9ac5c0f911a1 Mon Sep 17 00:00:00 2001 From: Michael Kennedy Date: Thu, 16 Jul 2026 22:41:29 -0700 Subject: [PATCH 8/8] Add a TL;DR; at the top and dedup the headings. --- change-log.md | 11 +++++++++++ install-python.md | 35 ++++++++++++++++++++--------------- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/change-log.md b/change-log.md index d6f8268..0572ca4 100644 --- a/change-log.md +++ b/change-log.md @@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +### Added + +- **Answer-first opening.** The guide now leads with the actual answer โ€” install uv, then run `uv python install 3.14 --default` โ€” before the welcome. Previously the first text was a greeting and the two commands didn't appear until a third of the way down, so anything quoting the top of the article (search snippets, AI assistants) found no answer to "how do I install Python." +- **Attribution and freshness line** under the title (last updated, Python version covered, author). Readers landing cold couldn't tell whether the guide was from 2019 or last week, which matters more here than on most pages because installing Python has changed so much. +- **Source link for the "10-100x faster than pip" claim**, pointing at Astral's published benchmarks. It was the most quotable number in the article and the only one with nothing behind it. +- **Alt text on the `python: command not found` screenshot.** It was the first element after the title and was announced as nothing at all to screen readers. + +### Changed + +- **Per-OS step headings are now self-contained.** `Step 1. Install uv` appeared three times identically, under Windows, macOS, and Linux, with different and mutually incompatible commands underneath. Anything that reads the article by section โ€” including AI assistants โ€” had three identically-labeled sections to choose from, and could hand a Windows reader the `curl` command. Each heading now names its OS (`Step 1. Install uv on Windows`), and the OS `##` headings match how people actually search ("How to Install Python on Windows"). The hand-rolled `#windows` / `#macos` / `#linux` jump-link anchors are unaffected. + ## [2026.07.16] - python-default-flag ### Fixed diff --git a/install-python.md b/install-python.md index 0b018c8..f57bbbd 100644 --- a/install-python.md +++ b/install-python.md @@ -1,6 +1,11 @@ # How to Install Python 3.14 with uv - +A terminal window showing a 'python: command not found' error โ€” the problem this guide solves + +**Last updated:** July 16, 2026 ยท **Covers:** Python 3.14 ยท **By:** [Michael Kennedy](https://talkpython.fm/), host of the [Talk Python To Me](https://talkpython.fm/) podcast + +tl;dr; **To install Python 3.14 on Windows, macOS, or Linux, you run two commands:** first install [uv](https://docs.astral.sh/uv/), then run `uv python install 3.14 --default`. That's the whole process - no installer wizard, no decision tree, no editing your `PATH`, and the same two steps on every operating system. Copy-paste instructions for each platform are below. +
Welcome, soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below). @@ -21,9 +26,9 @@ That's it! Jump to your operating system to get started:
-## Windows +## How to Install Python on Windows -### Step 1. Install uv +### Step 1. Install uv on Windows Open [**PowerShell**](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell) or [**Windows Terminal**](https://apps.microsoft.com/detail/9n0dx20hk701) and run: @@ -33,7 +38,7 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie After installation completes, **close and reopen your terminal** for the changes to take effect. -### Step 2. Install Python +### Step 2. Install Python on Windows Now install Python 3.14 with a single command: @@ -52,7 +57,7 @@ Installed Python 3.14.6 in 2.1s Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. -### Step 3. Verify It Works +### Step 3. Verify Python Works on Windows ```powershell python -V @@ -69,9 +74,9 @@ If PowerShell says `python` isn't recognized, close and reopen your terminal so **You're all set!** ๐ŸŽ‰
-## macOS +## How to Install Python on macOS -### Step 1. Install uv +### Step 1. Install uv on macOS Open the [**Terminal**](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) and run: @@ -81,7 +86,7 @@ curl -LsSf https://astral.sh/uv/install.sh | sh After installation completes, **close and reopen your terminal** for the changes to take effect. -### Step 2. Install Python +### Step 2. Install Python on macOS Now install Python 3.14 with a single command: @@ -100,7 +105,7 @@ Installed Python 3.14.6 in 1.9s Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. -### Step 3. Verify It Works +### Step 3. Verify Python Works on macOS ```bash python -V @@ -117,9 +122,9 @@ If you get a `command not found` error, close and reopen your terminal so it pic **You're all set!** ๐ŸŽ‰ _________________________ -## Linux +## How to Install Python on Linux -### Step 1. Install uv +### Step 1. Install uv on Linux Open a [**terminal**](https://ubuntu.com/tutorials/command-line-for-beginners) and run: @@ -129,7 +134,7 @@ curl -LsSf https://astral.sh/uv/install.sh | sh After installation completes, **close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`) for the changes to take effect. -### Step 2. Install Python +### Step 2. Install Python on Linux Now install Python 3.14 with a single command: @@ -148,7 +153,7 @@ Installed Python 3.14.6 in 1.5s Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet. -### Step 3. Verify It Works +### Step 3. Verify Python Works on Linux ```bash python -V @@ -255,7 +260,7 @@ _________________________ **[uv](https://docs.astral.sh/uv/)** is developed by [Astral](https://astral.sh/), the creators of [Ruff](https://docs.astral.sh/ruff/) (the popular Python linter). It's designed to be: -- โšก๏ธ **Blazing fast** - 10-100x faster than pip +- โšก๏ธ **Blazing fast** - 10-100x faster than pip ([see Astral's benchmarks](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md)) - ๐Ÿ **Python version manager** - installs and manages Python itself - ๐Ÿ“ฆ **Package manager** - replaces pip, pip-tools, and virtualenv - ๐Ÿ”’ **Lockfile support** - reproducible environments @@ -273,4 +278,4 @@ If you find a problem or have a suggestion to make this page better, please open + \ No newline at end of file