%%{init: {"flowchart": {"diagramPadding": 40}}}%%
flowchart TD
A(["Start"]) --> B{"Your operating system?"}
B -- "Windows" --> W["Python install manager<br/>py install 3.14"]
B -- "macOS" --> M["python.org installer<br/>or Homebrew"]
B -- "Linux" --> L{"Is Python 3.14 in<br/>the distro packages?"}
L -- "Yes" --> L1["Install from distro packages"]
L -- "No / unsure" --> L2["Use uv or pyenv"]
A --> U["Shortcut on every system:<br/>uv python install 3.14"]
W --> V["Create a venv per project"]
M --> V
L1 --> V
L2 --> V
U --> V
V --> Z(["Check with the checker script"])
Appendix A — Installing on Windows, Linux, and macOS
All scripts of this appendix are in the folder kode/ch71/. In the web version you can also download them all at once (zip).
Chapter 4 already walked you through installing Python on Windows. This appendix completes it: it gathers all operating systems in one place, adds how to create virtual environments and supporting tools, and ends with a “if this happens, try that” list. Think of it as the manual in the workshop drawer: you do not read it from start to finish, you open it when a bolt is stuck.
Honesty first: what was tested and what was not
This book was written and run on one Windows 11 computer. Therefore:
| Part | Status | Basis |
|---|---|---|
Windows (Python install manager, py, venv, uv) |
Tested on the author’s computer | Commands were run; output is shown |
| Linux (distribution packages, pyenv, uv) | Not tested on Linux | Official documentation, read 2026-10-10 |
| macOS (python.org installer, Homebrew, uv) | Not tested on macOS | Official documentation, read 2026-10-10 |
Every Linux and macOS command below is marked with its source. When I could not find a command in the official documentation, I write not verified instead of presenting it as fact. Version numbers on your computer may differ from those shown here.
The terminal: where you type commands
All commands in this appendix are typed in a terminal (explained in Chapter 3):
- Windows: open PowerShell (search for “PowerShell” in the Start menu).
- macOS: open the Terminal app (in Launchpad, folder Other).
- Linux: open the Terminal app from your application menu.
The $ at the start of Linux and macOS example lines is just the “ready for a command” sign (the prompt). Do not type it.
NoteREMEMBER
Python has two confusing “names”: python and python3. On Windows with the Python install manager, both python and py work. On Linux and macOS, get used to typing python3, because python is sometimes missing or points to another version.
Decision map: which way to install?
Trace it from the oval Start. Almost every route ends at the same step: create a venv per project (section below), then check the result.
Windows
The Python install manager
The official Python 3.14 documentation for Windows (docs.python.org/3.14/using/windows.html, read 2026-10-10) names the Python install manager as the recommended way. The old single-file installer has been deprecated since 3.14 and will not be produced for Python 3.16 and later. There are three ways to install the manager itself:
- Microsoft Store: find the Python install manager app and click Install.
- MSIX file from python.org: download it from python.org/downloads, double-click, choose Install. The Store and python.org packages are identical, but cannot be installed at the same time.
- MSI (for special cases, for example Windows Server 2019): no user interface, installs for the whole computer. Beginners do not need this.
Once the manager is installed, install Python itself:
py install 3.14Other manager commands listed in the same documentation:
| Command | What it does |
|---|---|
py list |
Shows the Python runtimes that are installed |
py list --online 3.14 |
Shows what can be installed |
py install 3.14 |
Installs Python 3.14 |
py uninstall 3.14 |
Removes Python 3.14 |
py -V:3.14 script.py |
Runs a script with Python 3.14 (this option must come first) |
py install --refresh |
Recreates Start menu shortcuts and aliases |
Checking the version
py --versionOn the author’s computer: Python 3.14.8. This works with both the old and the new launcher. The manager’s documentation does not discuss py --version specifically; the proof comes only from the author’s test above.
The PATH folders
The documentation lists adding %LocalAppData%\Python\bin to the PATH (the list of folders where Windows looks for programs) as optional, not required. Also keep %UserProfile%\AppData\Local\Microsoft\WindowsApps on the PATH, because removing it can break shortcuts.
Installing from a script (optional)
For automated installation, the official documentation suggests WinGet:
winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity
py install --configure -yThis code was not run when the book was built because it changes the author’s computer, so no output is shown; the commands were copied from the official documentation above.
Linux
Status: not tested on Linux. The content of this section comes from the official documentation (docs.python.org/3.14/using/unix.html, read 2026-10-10).
Python from distribution packages
The official documentation states that Python comes preinstalled on most Linux distributions and is available as a package on the others. It does not give an install command for Python itself (it leaves that to each distribution’s guides). First check what you have:
$ python3 --versionThe version may not be 3.14: that depends on your distribution and release, and I cannot confirm it for your distro. This book was run with Python 3.14.8; nearly all scripts were also tried on 3.12.10 with the same results (see the TIP box in Chapter 4), but Chapter 47 covers features that exist only in certain versions.
The official documentation does give commands for IDLE (Python’s built-in editor), which is sometimes not installed along with Python:
$ sudo apt update && sudo apt install idle # Debian and Ubuntu
$ sudo dnf install python3-idle # Fedora, RHEL, CentOS
$ sudo zypper install python3-idle # SUSE and openSUSE
$ sudo apk add python3-idle # Alpine
NoteREMEMBER
On Linux, python3 -m venv and pip are sometimes provided as separate packages by the distribution. The official Python packaging guide writes: “On Linux, you may have to install an additional package such as python3-pip”. The exact package name for venv on your distro (on Debian and Ubuntu probably python3-venv) is not verified against distribution documentation; if python3 -m venv complains about ensurepip, look for your distribution’s venv package.
pyenv: installing many Python versions
pyenv installs several Python versions side by side by compiling them. According to github.com/pyenv/pyenv (read 2026-10-10):
$ curl -fsSL https://pyenv.run | bash
$ pyenv install -l # list versions that can be installed
$ pyenv install 3.14 # a version prefix maps to the latest matching release
$ pyenv global 3.14Before pyenv install, install the build dependencies first; the list is in the pyenv wiki, section “Suggested build environment”. Pyenv also needs shell setup (the line eval "$(pyenv init - bash)" in ~/.bashrc, or the equivalent for zsh and fish; see its README). Because pyenv compiles Python, installation can take several minutes.
Note: the pyenv README states that pyenv does not support Windows outside WSL (Windows Subsystem for Linux); for Windows it recommends a fork called pyenv-win. This book does not cover pyenv-win.
Building from source
The official documentation gives the sequence ./configure, make, make install, but recommends make altinstall so that the system’s own python3 file is not overwritten. This is an advanced route; beginners should use uv or pyenv.
macOS
Status: not tested on macOS. Sources: docs.python.org/3.14/using/mac.html and docs.brew.sh/Language-Runtimes-and-Packages, read 2026-10-10.
The installer from python.org
Download the installer from python.org/downloads and double-click it. According to the official documentation, this installer is universal2 (it runs on both Apple Silicon and Intel Macs) and needs a macOS account with Administrator rights. The result: a Python 3.14 folder in Applications (containing IDLE and Python Launcher), a framework in /Library/Frameworks/Python.framework, and links in /usr/local/bin/.
Afterwards, double-click Install Certificates.command in the folder /Applications/Python 3.14/. This installs security certificates so Python can download from the internet. The sign of success: the text Successfully installed certifi and update complete appears.
Run Python with python3 (or python3.14):
$ python3 --version
WarningWARNING
macOS ships Apple’s own /usr/bin/python3. The official documentation calls it “usually older and incomplete”, made for Apple’s developer tools, and says it must not be modified or deleted. After installing from python.org, your python3 should already point to the new one; if in doubt, check with which python3.
Homebrew
Homebrew is a package manager for macOS (brew.sh). The Python documentation lists it as an alternative distribution that is not maintained by the core Python team. The Homebrew documentation says its default Python formula installs python3 and pip3, and advises installing project dependencies in a venv, not in Homebrew’s base environment (which is marked “externally managed” under PEP 668). The Homebrew documentation I read does not literally contain the command brew install python (it tells you to use brew info python to see the current version); the VS Code guide writes brew install python3. So check with brew info python first.
uv: the shortcut on every system
uv (introduced in Chapter 17) can install Python and also manage projects. According to docs.astral.sh/uv (read 2026-10-10), to install uv:
# macOS and Linux
$ curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# alternatives: Homebrew (macOS) or WinGet (Windows)
$ brew install uv
winget install --id=astral-sh.uv -eThen Python itself (from the uv guide):
uv python install 3.14 # install Python 3.14
uv python list # see what is available and installed
uv venv # create a venv; installs Python first if missingAccording to that guide, uv uses a Python already on the system when it fits and, by default, downloads the Python it needs. On the author’s computer, uv --version answers uv 0.11.28; uv was already installed, so installing uv itself was not retested.
CautionTECHNICAL STUFF (feel free to skip)
The command curl ... | sh downloads a script and runs it immediately. It is official and common, but you should get used to reading the script first (open its address in a browser) or using a package manager (brew, winget). Try it first on a computer that is not a production machine.
Virtual environments (venv) on each system
Chapter 17 explains why every project needs a venv. This is a summary of how on each system, from the official packaging guide and docs.python.org/3.14/library/venv.html (read 2026-10-10):
| Step | Windows (PowerShell) | Linux and macOS (bash/zsh) |
|---|---|---|
| Create | py -m venv .venv |
python3 -m venv .venv |
| Activate | .venv\Scripts\Activate.ps1 |
source .venv/bin/activate |
In cmd.exe |
.venv\Scripts\activate.bat |
(not applicable) |
| Check | where python |
which python |
| Check pip | py -m pip --version |
python3 -m pip --version |
| Deactivate | deactivate |
deactivate |
Once active, the venv folder name appears at the start of the prompt, and python points to the Python inside the venv.
TipTIP
You do not have to activate a venv. The official documentation says you can simply call the Python inside it by full path, for example .venv\Scripts\python.exe script.py on Windows or .venv/bin/python script.py on Linux and macOS. That is how this book’s project is run.
A real test: creating a venv from a script
Python can create a venv through the venv module (the same one the -m venv command uses). This script builds one in the _tmp/ folder, then inspects its contents:
02_create_venv.py
# Appendix A - Creating a virtual environment (venv) from Python
import shutil
import subprocess
import sys
import venv
from pathlib import Path
folder = Path(__file__).parent / "_tmp" / "venv_example"
if folder.exists():
shutil.rmtree(folder) # only this script's own example folder
venv.create(folder, with_pip=True)
print("Environment created:", folder.exists())
# On Windows the programs live in Scripts/, on Linux and macOS in bin/
sub = "Scripts" if sys.platform == "win32" else "bin"
contents = sorted(p.name for p in (folder / sub).iterdir())
print("Contents of folder", sub + ":", ", ".join(contents[:6]), "...")
venv_python = folder / sub / ("python.exe" if sys.platform == "win32" else "python")
for arguments in (["--version"], ["-m", "pip", "--version"]):
result = subprocess.run([str(venv_python), *arguments], capture_output=True, text=True)
text = result.stdout.strip()
label = "python " + " ".join(arguments[:2])
print(f"{label:<18}->", text.split(" from ")[0]) # drop the pathEnvironment created: True
Contents of folder Scripts: Activate.ps1, activate, activate.bat, activate.fish, deactivate.bat, pip.exe ...
python --version -> Python 3.14.8
python -m pip -> pip 26.2.1The first line proves the venv was created. The second shows the contents of the Scripts folder on Windows: there are activate, Activate.ps1, activate.bat, and so on (on Linux and macOS the activation scripts are in bin/). The last two lines call Python and pip inside the venv directly, without activation. In this fresh venv pip was installed along with it. The pip version number will change over time; what matters is that it answers.
WarningWARNING
In Windows PowerShell, Activate.ps1 is sometimes refused with a message about the execution policy (the rule for running scripts). The official documentation names the cure: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser. That changes a security setting of your account, so consider other routes: use cmd.exe with activate.bat, or do not activate the venv at all (see the TIP above). The policy on the author’s computer was not tested for this case.
Checking your environment
Run this checker script on your computer. It records the Python version, the operating system, whether needed modules are present, and whether some commands are found on the PATH:
01_check_environment.py
# Appendix A - Checking the Python environment on your computer
import platform
import shutil
import sys
print(f"{'Python version':<16}: {platform.python_version()}")
print(f"{'Operating system':<16}: {platform.system()}")
print(f"{'Architecture':<16}: {platform.machine()}")
print(f"{'Series 3.14?':<16}: {'yes' if sys.version_info[:2] == (3, 14) else 'no'}")
# Standard modules needed for virtual environments
for module in ("venv", "ensurepip", "tkinter", "sqlite3"):
try:
__import__(module)
status = "present"
except ImportError:
status = "MISSING"
print(f"{'module ' + module:<16}: {status}")
# Commands searched for on PATH (the result differs on every computer)
for command in ("python", "py", "uv", "git", "code"):
status = "found" if shutil.which(command) else "not found"
print(f"{'command ' + command:<16}: {status}")Python version : 3.14.8
Operating system: Windows
Architecture : AMD64
Series 3.14? : yes
module venv : present
module ensurepip: present
module tkinter : present
module sqlite3 : present
command python : found
command py : found
command uv : found
command git : found
command code : foundThis is the output of the author’s computer; yours will differ on the operating system, architecture, and found-command lines. How to read it:
- Python version and Series 3.14? tell you whether you are on the book’s reference version.
- module venv / ensurepip must be
present. IfMISSINGon Linux, see the REMEMBER box in the Linux section. - module tkinter is only needed for the windowed interface example in Chapter 42; sqlite3 for Chapter 24.
- command …
foundmeans it is on the PATH.not foundis not an error: it only means that command is not installed yet or not on the PATH.
Other tools this book uses
| Tool | What for | How to install | Required? |
|---|---|---|---|
| VS Code | Code editor | code.visualstudio.com | No (Notepad is enough for beginners) |
| Git | Version tracker (Chapter 20) | git-scm.com/downloads | From Chapter 20 |
| Quarto | Building this book | - | Not needed to read or follow the book |
The VS Code guide (read 2026-10-10) says: install the Python extension, then choose the interpreter through the Command Palette with the command Python: Select Interpreter. For Windows it checks the installation with py -3 --version. On the author’s computer VS Code and Git are installed (code and git are found by the checker script; git --version answers git version 2.55.0.windows.3), but the process of installing them was not retested.
Heavy tools needed only by particular chapters are explained in those chapters: PostgreSQL and PostGIS (Chapters 24 and 40), QGIS (Chapter 40), Redis (Chapter 67), Docker (Chapter 48), and the NVIDIA driver and CUDA (Chapter 55). Install them only when you reach that chapter.
Common problems and their solutions
| Symptom | Likely cause | What to try |
|---|---|---|
py not recognised (Windows) |
Install manager not installed, or alias turned off | Install the manager (see the Windows section); open a new terminal after installing |
py list / py install answers “can’t open file” |
The old py.exe takes priority |
Use pymanager list; or uninstall the old “Python launcher” from Installed apps (per the official documentation) |
python opens the Microsoft Store (Windows) |
Store alias active without Python installed | Install Python first; the py command can still be used |
python not found (Linux/macOS) |
Only python3 exists |
Type python3; inside an active venv, python is available |
pip gives externally-managed-environment |
Distro/Homebrew Python forbids global installs (PEP 668) | Create a venv, then install there; do not use --break-system-packages |
python3 -m venv fails about ensurepip (Linux) |
The distro’s venv package is not installed | Look for your distro’s venv package (package name not verified) |
Activate.ps1 refused |
PowerShell execution policy | Use activate.bat in cmd, or call the venv’s python.exe directly |
| Library fails to install because there is no compiler | No ready-made package (wheel) for your Python/OS | Try an older Python, uv, or conda (Chapters 17 and 38) |
| SSL certificate fails (macOS python.org) | Forgot to run Install Certificates.command |
Run that file (see the macOS section) |
| Script “cannot find module” although it is installed | Installed in a different venv/Python than the one running the script | Run python -m pip install ... with the same Python; check which python / where python |
| Venv broken after the folder was moved | Venvs cannot be moved or copied | Recreate the venv (per the official documentation) and reinstall from requirements.txt |
The rows about py list, externally-managed-environment, Activate.ps1, a moved venv, and SSL certificates come from the official documentation quoted in this appendix. The other rows are common experience that I did not test on the author’s computer (label: probable); the venv package name on Linux is even not verified.
NoteREMEMBER
When confused, go back to basics: (1) py --version or python3 --version, (2) create a venv in the project folder, (3) call the Python inside the venv by full path. Those three steps solve most installation problems.
Next: Appendix B summarises the key commands in cheat sheets. If you are looking for a study order, jump to Appendix E.