Skip to content

[Python] Update the Python Installation Chapter #168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JakobKlotz merged 8 commits into from
Mar 5, 2026
Merged

[Python] Update the Python Installation Chapter #168

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3d89aa6
docs: remove troubleshooting section (not needed anymore)
JakobKlotz Feb 12, 2026
ae513be
docs: update Windows install instructions
JakobKlotz Feb 12, 2026
3fac3a7
docs (fix): broken gif link
JakobKlotz Feb 25, 2026
baecfda
docs: update Python installation on macOS
JakobKlotz Feb 25, 2026
7c7f70e
docs: use a info admonition
JakobKlotz Feb 25, 2026
78ed348
docs: use a info admonition for Win10 users
JakobKlotz Feb 27, 2026
649eaea
docs (chore): open links in blank target
JakobKlotz Feb 27, 2026
d507fba
docs (chore): do not display related videos
JakobKlotz Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 116 additions & 158 deletions docs/python/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,211 +5,169 @@ In this section, we will guide you through the installation process of

???+ danger

Before you skip the content and proceed with the installation, we encourage
you to read our instructions. Following them, will save you some time
and potential headaches with the setup process!
Before you skip the content and proceed with the installation, we encourage you
to read our instructions. Following them, will save you some time and potential
headaches with the setup process!

---
______________________________________________________________________

## Step 1: :fontawesome-solid-download: Download
=== ":fontawesome-brands-windows: Windows"

We urge you to install **:fontawesome-brands-python: Python** `3.12.9`.
Visit the official website [python.org :octicons-link-external-16:](https://www.python.org/downloads/release/python-3129/),
scroll to the bottom of the page and download the installer for your operating
system.
Following video walks you through the installation steps for
:fontawesome-brands-windows: Windows.

Now, <span style="color:red">do not run the installer just yet</span> - watch
the below video first! It will save you time! :ok_hand:
<div style="text-align: center;">
<iframe width="840" height="480"
src="https://www.youtube.com/embed/wqawj4XK8UE?si=Wjlt4L-KfU7Ho2qQ&rel=0"
title="YouTube video player" frameborder="0" allow="accelerometer;
autoplay; clipboard-write; encrypted-media; gyroscope;
picture-in-picture; web-share"
referrerpolicy="strict-origin-when-cross-origin"
allowfullscreen style="border-radius: 15px;">
</iframe>
</div>

???+ tip ":fontawesome-brands-apple: Are you on Apple silicon?"
???+ info

If you prefer a written guide follow the next couple of sections.

If you are using an Apple silicon Mac (M1, ... M4), you can also pick
the `macOS 64-bit universal2 installer`.
<h2>Step 1: :fontawesome-solid-download: Download</h2>

## Step 2: :fontawesome-solid-arrow-pointer: Run installer
We recommend installing **:fontawesome-brands-python: Python** `3.14`!

No matter which operating system you're on, When installing Python, make sure
that you check the box `Add python to PATH`!
1. Visit the official website
[python.org :octicons-link-external-16:](https://www.python.org){target="_blank" rel="noreferrer"}
1. Navigate to **Downloads**
1. A section **"Download for Windows"** will automatically appear
1. Click the button **Python install manager**
1. Locate the downloaded `.msix` file in your Downloads folder

Now run the Python installer.
<h2>Step 2: :fontawesome-solid-arrow-pointer: Run installer</h2>

=== ":fontawesome-brands-windows: Windows"
1. Double-click the `.msix` file to launch the install manager.

<div style="text-align: center;">
<iframe
width="840" height="473"
src="https://www.youtube.com/embed/fpxdo5QYvmM?si=vjsmF84v80GsgeK6"
title="YouTube video player" frameborder="5"
allow="accelerometer; autoplay; clipboard-write; encrypted-media;
gyroscope; picture-in-picture;"
referrerpolicy="strict-origin-when-cross-origin"
>
</iframe>
</div>
1. Click **"Install Python"** to begin the installation

After the successful installation, we recommend to open a command prompt
(use the Windows search with the keyword `cmd`) and verify the installation
by typing
1. A new Terminal window will open

```commandline
python --version
```
1. **Optional:** If prompted with "Open Settings to modify App execution
aliases":

which should result in

```title="CMD Output"
Python 3.12.9
```
- Type `y` and press ++enter++
- In the Settings app, search for `alias`
- Navigate to **App execution aliases**
- Toggle the Python aliases **on**

=== ":fontawesome-brands-apple: macOS"

???+ info
???+ info

Unfortunately, we do not have a installation video for macOS (yet).
If you're having any trouble, please reach out to us!
The app alias configuration is an optional step that may appear during
installation. It might not be necessary on your machine. Properly configured
aliases allow you to execute Python commands from the terminal.

Nevertheless, the installation process is straightforward. Double click the
downloaded `python-3.12.9-macos11.pkg` file and follow the installation
instructions.
1. When prompted `Install CPython now? [Y/n]`:

Make sure to `Add python to PATH` during the installation process!
- Press ++enter++ to accept the default option (Yes)

After the successful installation, open a terminal (use the spotlight search
with the keyword `terminal`) and verify the installation by typing
1. When prompted `View online help? [y/N]`:

```bash
python3 --version
```
- Press ++enter++ to skip this step
- The terminal will close automatically

which should result in

```
Python 3.12.9
```
<h2>Step 3: :fontawesome-solid-check-circle: Verify Installation</h2>

---
1. Open a new terminal window (use Windows search with the keyword
`terminal`)
Copy link
Copy Markdown
Member

@verenitas verenitas Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned I would go with cmd here.

Copy link
Copy Markdown
Member Author

@JakobKlotz JakobKlotz Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about an additional info box?

    ???+ info

        If you are using Windows 10 (installed on our MCI computers), 
        search for **Command Prompt** (`cmd`) instead of Terminal. All 
        consecutive steps stay the same.

Copy link
Copy Markdown
Member

@manuf3006 manuf3006 Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about an additional info box?

    ???+ info

        If you are using Windows 10 (installed on our MCI computers), 
        search for **Command Prompt** (`cmd`) instead of Terminal. All 
        consecutive steps stay the same.

I dont know, if we want to mention MCI since we are trying to separate it from the course for a broader audience?

Copy link
Copy Markdown
Member

@verenitas verenitas Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is perfect :)

Copy link
Copy Markdown
Member Author

@JakobKlotz JakobKlotz Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, made the change and removed the mention of MCI 😄


## Step 3: :fontawesome-solid-check: Done!
???+ info

If everything went smoothly, you have successfully installed
**:fontawesome-brands-python: Python**! You can now skip the
troubleshooting part and proceed with the next chapter. :party_popper:
If you are using Windows 10, search for **Command Prompt** (`cmd`)
instead of Terminal. All consecutive steps stay the same.

<div style="text-align: center;">
<iframe src="https://giphy.com/embed/XreQmk7ETCak0"
width="336" height="252" style="" frameBorder="0" class="giphy-embed"
allowFullScreen
>
</iframe>
</div>
1. Check your installation by running:

---
```commandline
python --version
```

## Optional: Troubleshooting
1. You should see output similar to:

???+ info
```
Python 3.14.x
```

The troubleshooting section is specific to :fontawesome-brands-windows:
Windows. If you're on :fontawesome-brands-apple: macOS and encounter
issues, please reach out to us!
where `x` represents the specific patch version (e.g., `3.14.3` or
`3.14.4`).

### PATH issues
=== ":fontawesome-brands-apple: macOS"

If you didn't check the box `Add python.exe to PATH` during
installation, or you encounter an error message along the lines of
???+ info

```commandline
'python' is not recognized as an internal or external command
```
Unfortunately, we do not have a installation video for macOS (yet).
If you're having any trouble, reach out to us!

<h2>Step 1: :fontawesome-solid-download: Download</h2>

you need to add Python to your PATH (the error means that
**:fontawesome-brands-python: Python** is simply not found).
We recommend installing **:fontawesome-brands-python: Python** `3.14`.

We cover two options to fix the PATH issue, either use the command prompt
or the GUI.
1. Visit the official website
[python.org :octicons-link-external-16:](https://www.python.org){target="_blank" rel="noreferrer"}
1. Navigate to the **Downloads** tab
1. A section **"Download for macOS"** will automatically appear
1. Click the **Python 3.14.x** button to download
1. Locate the downloaded `.pkg` file in your Downloads folder

=== "Option 1: GUI"
<h2>Step 2: :fontawesome-solid-arrow-pointer: Run installer</h2>

**Step 1**:
1. Double-click the `.pkg` file to launch the installer
1. Follow the installation wizard:
- Click **Continue** through the introduction screens
- Accept the license agreement
- Click **Install** and enter your password if prompted
- Wait for the installation to complete

First, we need to find the path to the executable.

Open the :fontawesome-brands-windows: Windows search and type `python`.
Select `Dateispeicherort öffnen` (open file location). Open the context menu
of `Python` (that's just a shortcut) and select `Eigenschaften` (properties)
:octicons-arrow-right-24: `Dateipfad öffnen` (open file path).
Lastly, copy the path of the newly opened explorer window.

<img
height="750" src="/assets/python/installation/get-path.gif"
style="border-radius: 10px;"
/>
<figcaption style="text-align: center;">
Determine the path to the Python executable.
</figcaption>

**Step 2**:

Now, we need to add the path to the environment variables. Again use
the :fontawesome-brands-windows: Windows search and type
`Umgebungsvariablen` (Environment variables). Select the Path value in the
`Benutzervariablen für <user-name>` (User variables) section. Click on
`Neu` (New) and paste the copied path.

<div style="text-align: center;">
<img
height="750" src="/assets/python/installation/add-path.gif" width="400"
style="border-radius: 10px;"
/>
<figcaption style="text-align: center;">
Add the path to the user variables.
</figcaption>
</div>
???+ danger

=== "Option 2: Command prompt"
**Important:** After installation completes, Finder will automatically open,
showing the Python installation folder. You **must** complete this final step:

- Double-click the `Install Certificates.command` file
- A Terminal window will open and execute the certificate installation
- Wait for it to complete and close automatically

This step is required for Python to make secure HTTPS connections.

**Step 1**:
<h2>Step 3: :fontawesome-solid-check-circle: Verify Installation</h2>

Determine the path to the **:fontawesome-brands-python: Python** executable
using the Python launcher `py` (which is part of the Python installation and
is on PATH by default).
1. After the successful installation, open a terminal (use the spotlight
search with the keyword `terminal`)


```commandline
py -3.12 -c "import sys; print(sys.executable)"
```

In my case, the output is:
1. Verify the installation by typing:


```title="CMD Output"
C:\Users\ztklotz\AppData\Local\Programs\Python\Python312\python.exe
```

Copy your path *without* the `python.exe` part.

**Step 2**:

Set the PATH variable using the command prompt.
```bash
python3 --version
```


```commandline
setx PATH "%PATH%;<copied-path>"
```

For instance (using my path):
1. You should see output similar to:


```commandline
setx PATH "%PATH%;C:\Users\ztklotz\AppData\Local\Programs\Python\Python312"
```
```
Python 3.14.x
```

**Step 3**:
where `x` represents the specific patch version (e.g., `3.14.3` or
`3.14.4`).

Again, verify the installation by typing `python --version` within a command
prompt.
______________________________________________________________________

<h2>Done!</h2>

If everything went smoothly, you have successfully installed
**:fontawesome-brands-python: Python**! :tada:

<div style="text-align: center;">
<img src="https://media.giphy.com/media/111ebonMs90YLu/giphy.gif" />
</div>

---
______________________________________________________________________

With **:fontawesome-brands-python: Python** installed, the next step is to set
up a code editor. In the following section, we will install Visual Studio Code
Expand Down