Skip to content

Commit 3adbd96

Browse files
mikeckennedymikeckennedy
committed
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
1 parent 132958b commit 3adbd96

4 files changed

Lines changed: 79 additions & 39 deletions

File tree

‎.rumdl.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ exclude = ["node_modules", "build", "dist"]
44
respect-gitignore = true
55

66
# Disable specific rules
7-
disabled-rules = ["MD013", "MD033"]
7+
disable = ["MD013", "MD033"]
88

99
# Configure individual rules
1010
[MD007]
@@ -23,4 +23,4 @@ tables = false
2323
names = ["rumdl", "Markdown", "GitHub"]
2424

2525
[MD048]
26-
code-fence-style = "backtick"
26+
style = "backtick"

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Installing Python
22

3-
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.
3+
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/).
44

55
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)**.
66

7-
See the article source via [`install-python.md`](./install-python.md).
7+
See the article source via [`install-python.md`](./install-python.md), and notable changes in [`change-log.md`](./change-log.md).
88

9-
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.
9+
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.

‎change-log.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
66

77
## [Unreleased]
88

9+
### Fixed
10+
- **`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.
11+
- 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).
12+
- Corrected sample command output, which showed a `Searching for Python 3.14` line that uv does not print and omitted the installed executable names.
13+
- 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.
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.
15+
- 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.
16+
- 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.
17+
18+
### Added
19+
- Note that `--default` emits an experimental warning, so readers don't think the install failed.
20+
- 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.
21+
- Warning against using `--default` when installing multiple Python versions, plus how to intentionally repoint `python` at a different version later.
22+
- Explicit "close and reopen your terminal" reminder in each verification step.
23+
924
## [2025.12.10] - python-2025-guide
1025

1126
### Changed

‎install-python.md‎

Lines changed: 59 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
<img src="https://training.talkpython.fm/static/img/cms/nopy-final.jpg" style="border-radius: 10px; display: block;" class="img img-responsive" />
44

5-
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).
5+
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).
66

7-
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.
7+
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.
88

99
## The Modern Approach: Install uv, Then Python
1010

@@ -39,27 +39,32 @@ After installation completes, **close and reopen your terminal** for the changes
3939
Now install Python 3.14 with a single command:
4040

4141
```powershell
42-
uv python install 3.14
42+
uv python install 3.14 --default
4343
```
4444

45+
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.
46+
4547
You'll see output like:
4648

47-
```
48-
Searching for Python 3.14
49-
Installed Python 3.14.2 in 2.34s
50-
+ cpython-3.14.2-windows-x86_64-none
49+
```text
50+
Installed Python 3.14.6 in 2.1s
51+
+ cpython-3.14.6-windows-x86_64-none (python, python3, python3.14)
5152
```
5253

54+
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.
55+
5356
### Step 3. Verify It Works
5457

58+
**Close and reopen your terminal**, then run:
59+
5560
```powershell
56-
uv run python -V
61+
python -V
5762
```
5863

5964
You should see:
6065

61-
```
62-
Python 3.14.2
66+
```text
67+
Python 3.14.6
6368
```
6469

6570
**You're all set!** 🎉
@@ -84,31 +89,32 @@ After installation completes, **close and reopen your terminal** for the changes
8489
Now install Python 3.14 with a single command:
8590

8691
```bash
87-
uv python install 3.14
92+
uv python install 3.14 --default
8893
```
8994

95+
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.
96+
9097
You'll see output like:
9198

92-
```
93-
Searching for Python 3.14
94-
Installed Python 3.14.2 in 1.89s
95-
+ cpython-3.14.2-macos-aarch64-none
99+
```text
100+
Installed Python 3.14.6 in 1.9s
101+
+ cpython-3.14.6-macos-aarch64-none (python, python3, python3.14)
96102
```
97103

104+
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.
105+
98106
### Step 3. Verify It Works
99107

108+
**Close and reopen your terminal**, then run:
109+
100110
```bash
101111
python -V
102-
103-
# or
104-
105-
uv run python -V
106112
```
107113

108114
You should see:
109115

110-
```
111-
Python 3.14.2
116+
```text
117+
Python 3.14.6
112118
```
113119

114120
**You're all set!** 🎉
@@ -133,31 +139,32 @@ After installation completes, **close and reopen your terminal** (or run `source
133139
Now install Python 3.14 with a single command:
134140

135141
```bash
136-
uv python install 3.14
142+
uv python install 3.14 --default
137143
```
138144

145+
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.
146+
139147
You'll see output like:
140148

149+
```text
150+
Installed Python 3.14.6 in 1.5s
151+
+ cpython-3.14.6-linux-x86_64-gnu (python, python3, python3.14)
141152
```
142-
Searching for Python 3.14
143-
Installed Python 3.14.2 in 1.52s
144-
+ cpython-3.14.2-linux-x86_64-gnu
145-
```
153+
154+
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.
146155

147156
### Step 3. Verify It Works
148157

158+
**Close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`), then run:
159+
149160
```bash
150161
python -V
151-
152-
# or
153-
154-
uv run python -V
155162
```
156163

157164
You should see:
158165

159-
```
160-
Python 3.14.2
166+
```text
167+
Python 3.14.6
161168
```
162169

163170
**You're all set!** 🎉
@@ -181,21 +188,31 @@ This creates a `.venv` folder in your project. If Python 3.14 isn't already inst
181188
### Activating the Virtual Environment
182189

183190
**Windows (PowerShell):**
191+
184192
```powershell
185193
.venv\Scripts\Activate.ps1
186194
```
187195

188196
**macOS / Linux:**
197+
189198
```bash
190199
source .venv/bin/activate
191200
```
192201

193-
Once activated, you can use `python` directly:
202+
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:
194203

195204
```bash
196205
python -V
197206
```
198207

208+
In a project created with `uv venv --python 3.12`, that reports:
209+
210+
```text
211+
Python 3.12.13
212+
```
213+
214+
When you're finished working on the project, run `deactivate` and `python` goes back to your global 3.14.
215+
199216
### Installing Packages
200217

201218
With uv, installing packages is lightning fast:
@@ -220,7 +237,9 @@ Need multiple Python versions? uv handles that too:
220237
uv python install 3.12 3.13 3.14
221238
```
222239

223-
List installed versions:
240+
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.
241+
242+
List installed versions, including any that came with your system:
224243

225244
```bash
226245
uv python list
@@ -232,6 +251,12 @@ Create a virtual environment with a specific version:
232251
uv venv --python 3.12
233252
```
234253

254+
Want to move `python` to a different version later? Re-run the install with `--default`:
255+
256+
```bash
257+
uv python install 3.13 --default
258+
```
259+
235260
_________________________
236261

237262
## Why uv?

0 commit comments

Comments
 (0)