Appendix B: Environment Setup Guide

This appendix walks you through setting up a complete Python development environment from scratch. If you followed the installation instructions in Chapter 2, you may already have some or all of this in place — skim to the parts you need.

B.1 Python Installation

Which Version?

This textbook requires Python 3.13 or later, the same version Chapter 2 asks for. Install the newest stable release listed on python.org. When this appendix was written, that was 3.14.x, and Python 3.15 was scheduled for release in October 2026; whichever version python.org lists as the latest stable release when you read this is the one to get.

Windows

Since Python 3.14, python.org recommends the Python install manager for Windows: a small tool that downloads Python for you and keeps it up to date.

1. Get the install manager. Go to python.org/downloads and download the Python install manager, or install "Python Install Manager" from the Microsoft Store.

2. Run it and accept the defaults. If it offers to add a directory to your PATH, say yes. (PATH is the list of folders your terminal searches when you type a command name.)

3. Verify the installation. Open a terminal (see B.3 below) and type: python --version The first time, the install manager may take a minute to download the latest Python. Then you should see something like Python 3.14.0. If you see an error, or the Microsoft Store opens instead, see the Troubleshooting section (B.7).

4. Know the py command. The install manager also gives you py, which works even when python doesn't and can pick a version: py list shows the versions you have, py install 3.13 adds one, and py -3.13 my_script.py runs a script with it.

5. Verify pip. pip is Python's package installer and is included automatically: python -m pip --version You should see something like pip 26.2 from ... (your version number will differ).

The classic installer. python.org still offers the older "Windows installer" .exe, but it is deprecated and won't be produced for Python 3.16 or later. If you use it, check the box that says "Add python.exe to PATH" on the first screen. Skipping that checkbox is the single most common Windows installation problem.

macOS

1. Check for an existing installation. Open Terminal (Applications > Utilities > Terminal) and type: python3 --version Recent macOS versions include a python3 command that belongs to Apple's developer tools (Xcode or the Command Line Tools). It is usually an older version, and the first time you run it macOS may offer to install those tools. Leave Apple's copy alone and install a current Python alongside it.

2. Option A: Official installer (recommended for beginners). Go to python.org/downloads/macos and download the macOS installer (.pkg file). Double-click it and follow the wizard. When it finishes, a Finder window for /Applications/Python 3.x opens: double-click Install Certificates.command in it. That installs the security certificates Python needs to download anything over HTTPS; skip it and you may later hit SSL: CERTIFICATE_VERIFY_FAILED errors.

3. Option B: Homebrew (if you already use Homebrew). brew install python This installs Homebrew's current Python 3 as python3, with pip as pip3. Running pip3 install outside a virtual environment then stops with error: externally-managed-environment. That's expected: install packages inside a virtual environment (B.5).

4. Verify the installation: python3 --version pip3 --version

5. Important: On macOS, always use python3 and pip3, not python and pip, unless you're inside an activated virtual environment (B.5). Apple removed the old Python 2 in macOS 12.3, so on a stock Mac the bare python command usually doesn't exist at all.

Linux (Ubuntu/Debian)

1. Check what you already have. Most distributions come with Python 3 installed: python3 --version

2. If it's 3.13 or later (Debian 13, Ubuntu 25.04 and newer), install the extras the book needs: the venv module and pip. sudo apt update sudo apt install python3-venv python3-pip

3. If it's older (Ubuntu 24.04 LTS ships 3.12), add the widely used deadsnakes package archive and install 3.13 alongside the system Python: sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.13 python3.13-venv Then verify with python3.13 --version, and type python3.13 wherever this book says python. (deadsnakes supports Ubuntu only, not Debian.)

4. Don't repoint the system python3. Ubuntu's own tools depend on the version it shipped, and swapping it out (for example with update-alternatives) can break system programs in confusing ways. Call the new version by its full name, or create a virtual environment with it (python3.13 -m venv .venv); inside that environment, plain python means 3.13.

Linux (Fedora/RHEL)

Fedora ships a recent Python 3 as python3, so check it first:

python3 --version

If it's older than 3.13, install a newer one alongside it (sudo dnf install python3.13) and run it as python3.13. On RHEL and its relatives, the available versions depend on the release; check dnf search python3.

Verifying Your Installation — All Platforms

After installation, open a terminal and confirm three things (on Windows, type python where these say python3):

python3 --version         # Should show 3.13 or later
python3 -m pip --version  # Should show pip and the same Python version
python3 -c "print('Hello from Python!')"

If the last command prints Hello from Python!, you are ready for Chapter 2.

B.2 VS Code Installation

Visual Studio Code (VS Code) is a free, lightweight code editor that works on all three platforms. It is the recommended editor for this textbook.

Installing VS Code

1. Go to code.visualstudio.com and download the installer for your operating system.
2. Run the installer with default settings.
3. Launch VS Code after installation.

Installing the Python Extension

1. Open VS Code.
2. Click the Extensions icon in the left sidebar (it looks like four small squares) or press Ctrl+Shift+X (Windows/Linux) / Cmd+Shift+X (macOS).
3. Search for "Python" and install the extension published by Microsoft (it should be the first result, with millions of installs).
4. This extension provides syntax highlighting, code completion (IntelliSense), running and debugging. It also installs its companions Pylance, Python Debugger and Python Environments for you. Style-checking linters such as Pylint or Ruff are separate extensions you can add later.

Configuring VS Code for Python

After installing the extension:

1. Select the Python interpreter. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command Palette. Type "Python: Select Interpreter" and choose the Python 3.13+ installation you just set up.

2. Enable auto-save (optional but recommended). Go to File > Preferences > Settings, search for "auto save", and set it to "afterDelay" with a 1000ms delay. This prevents the "I forgot to save before running" problem.

3. Set the default terminal. On Windows, VS Code may default to PowerShell. If you prefer Git Bash or Command Prompt, open Settings and search for "terminal default profile windows."

Recommended Additional Extensions

B.3 Terminal / Command Line Basics

The terminal is a text-based interface for interacting with your computer. You will use it to run Python scripts, manage files, install packages, and use Git.

Opening a Terminal

Essential Terminal Commands

These commands work on macOS and Linux. PowerShell, the usual terminal on Windows and inside VS Code there, accepts most of them too, except touch. The classic Command Prompt (cmd) needs its own versions, noted in parentheses.

Navigating with the Terminal

A typical workflow for this course:

# Create a course folder
mkdir cs1
cd cs1

# Create a folder for Chapter 3 exercises
mkdir ch03
cd ch03

# Create a Python file (PowerShell: ni tip_calculator.py)
touch tip_calculator.py

# Open the current folder in VS Code
code .

On macOS, the code command works only after you run Shell Command: Install 'code' command in PATH once from VS Code's Command Palette. On Windows, the VS Code installer sets it up for you.

Running Python from the Terminal

# Run a script
python3 my_script.py

# Start the interactive REPL
python3

# Run a one-liner
python3 -c "print(2 ** 10)"

# Run a module (pytest must be installed first)
python3 -m pytest

# Check installed packages
python3 -m pip list

On Windows, replace python3 with python if that is how your installation is configured.

B.4 Creating and Running .py Files

Method 1: VS Code (Recommended)

1. Open VS Code.
2. Open a folder: File > Open Folder > select your project folder.
3. Create a new file: File > New File, or click the new-file icon in the Explorer panel.
4. Save it with a .py extension (e.g., hello.py).
5. Write your code.
6. Run it by clicking the play button (triangle) in the top-right corner, or press F5 for the debugger.

Method 2: Terminal

1. Create or navigate to your project folder.
2. Create the file (in PowerShell, use ni hello.py instead): bash touch hello.py
3. Edit it with any text editor (or use VS Code: code hello.py).
4. Run it: bash python3 hello.py

File Naming Rules

• Use lowercase letters and underscores: grade_calculator.py
• Do not use spaces in filenames: my script.py has to be quoted every time you type it in the terminal, and it can't be loaded with an import statement.
• Do not name your file the same as a Python module: do NOT name a file random.py, math.py, string.py, test.py, or csv.py. This will shadow the standard library module and cause confusing import errors.
• Start with a letter, not a number: 3_variables.py is a bad name, because import 3_variables is a syntax error. Use ch03_variables.py instead.

B.5 Virtual Environments

A virtual environment is an isolated Python installation that keeps each project's dependencies separate. This becomes important starting in Chapter 12 and is essential by Chapter 23.

Creating a Virtual Environment

# Navigate to your project folder
cd my_project

# Create the virtual environment (Windows: python -m venv .venv)
python3 -m venv .venv

-m venv runs the standard-library module venv, and .venv is the folder it creates, holding the environment's own python and pip. (macOS and Linux hide names that start with a dot; ls -a shows them.)

Activating the Virtual Environment

When activated, your terminal prompt changes to show (.venv) at the beginning, and python and pip now mean the environment's copies, on every platform:

(.venv) $ python --version
Python 3.14.0

Installing Packages in a Virtual Environment

Once activated, use pip normally:

pip install requests
pip install pytest
pip install rich

Packages installed here are isolated from your system Python and from other virtual environments. This is also the fix for the externally-managed-environment error that recent Debian, Ubuntu and Homebrew Pythons give when you run pip install outside an environment.

Saving and Restoring Dependencies

# Save current packages to a file
pip freeze > requirements.txt

# Install all packages from the file (on a different machine or fresh venv)
pip install -r requirements.txt

Deactivating

deactivate

VS Code and Virtual Environments

VS Code can detect virtual environments automatically. If it doesn't, press Ctrl+Shift+P / Cmd+Shift+P, type "Python: Select Interpreter", and choose the interpreter inside your .venv/ folder.

Best Practices

• Create one virtual environment per project.
• Never commit the virtual environment to version control. Since Python 3.13, venv puts a .gitignore inside the new folder so Git skips it automatically; listing .venv/ in your project's .gitignore as well does no harm.
• Always use requirements.txt to track dependencies.
• If something feels broken, delete the .venv/ folder and recreate it. Virtual environments are disposable.

B.6 Project Folder Structure

By mid-semester (around Chapter 12), your projects should follow this general structure:

my_project/
    .venv/                   # virtual environment (not committed to git)
    src/                     # your source code
        __init__.py
        main.py
        models.py
        utils.py
    tests/                   # your tests
        test_models.py
        test_utils.py
    data/                    # data files
        input.csv
    requirements.txt         # package dependencies
    README.md                # project description
    .gitignore               # files to exclude from git

For early chapters (1-10), a flat structure is fine:

ch03/
    tip_calculator.py
    grade_calculator.py
    exercises.py

B.7 Troubleshooting

"python" Is Not Recognized (Windows)

Symptom: Typing python in the terminal gives 'python' is not recognized as an internal or external command or opens the Microsoft Store.

Cause: Windows can't find your Python. The Store opening is a placeholder shortcut Windows ships for when no Python is installed (or the real one isn't reachable).

Fixes (try in order): 1. Close the terminal and open a new one. A terminal that was already open before you installed Python doesn't see the change. 2. Try py. It often works even when python doesn't. 3. Click Start, search for "Manage app execution aliases", and make sure the aliases for the Python install manager ("Python (default)") are switched on. 4. If you used the classic installer, run it again and check "Add python.exe to PATH" on the first screen. 5. As a last resort, add Python to PATH by hand: - Search for "Environment Variables" in the Start menu and choose "Edit environment variables for your account". - Under "User variables", find Path and click "Edit". - Add the folder that holds python.exe (for the classic installer, typically C:\Users\YourName\AppData\Local\Programs\Python\Python314\, plus its Scripts subfolder). - Open a new terminal.

"Permission Denied" (macOS/Linux)

Symptom: Running a script gives Permission denied.

Fixes: - Use python3 my_script.py instead of ./my_script.py. - If you must run it directly: chmod +x my_script.py and add #!/usr/bin/env python3 as the first line.

Multiple Python Versions Installed

Symptom: python runs Python 2, or python3 runs an older version than expected.

Diagnosis:

which python3          # macOS/Linux: shows path
where python           # Windows: shows path(s)
python3 --version      # check version

Fixes: - On macOS/Linux: always use python3 explicitly, or create an alias in your shell config (~/.bashrc or ~/.zshrc): bash alias python=python3 alias pip=pip3 - On Windows: run py list to see what's installed, then pick a version with py -3.13 my_script.py.

pip Install Fails

Symptom: pip install package_name gives an error.

Common causes and fixes: - error: externally-managed-environment (Debian, Ubuntu, Homebrew): your operating system is protecting its own Python. Create and activate a virtual environment (B.5) and install there. Adding --user doesn't get around it. - Permission error: Install into a virtual environment instead. Never use sudo pip install; it can damage the Python your operating system relies on. - pip not found: Use python3 -m pip install package_name instead. - SSL certificate error (CERTIFICATE_VERIFY_FAILED): on macOS with the python.org installer, double-click Install Certificates.command in /Applications/Python 3.x/. Elsewhere, upgrading pip (python3 -m pip install --upgrade pip) often helps; on a school or work network, a firewall that inspects traffic may be the cause, so ask IT. - Package not found: Check the spelling. Search pypi.org for the correct package name.

Import Errors After Installing a Package

Symptom: pip install requests succeeds, but import requests in your script gives ModuleNotFoundError.

Cause: The pip that installed the package and the Python that runs your script are different installations.

Fix: Install using the same Python:

python3 -m pip install requests
python3 my_script.py

Or use a virtual environment (the most reliable fix).

VS Code Uses the Wrong Python

Symptom: Code runs fine in the terminal but VS Code shows errors or uses a different Python version.

Fix: Press Ctrl+Shift+P / Cmd+Shift+P, type "Python: Select Interpreter", and choose the correct Python installation.

IndentationError in Code That Looks Fine

Symptom: Python raises TabError: inconsistent use of tabs and spaces in indentation (or another IndentationError) even though the code looks properly indented.

Cause: Your file mixes tabs and spaces. A tab and four spaces can look identical on screen, but Python counts them differently.

Fix: 1. In VS Code, go to Settings and search for "insert spaces". Make sure "Editor: Insert Spaces" is checked and "Editor: Tab Size" is set to 4. 2. To fix an existing file: open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run "Convert Indentation to Spaces". It converts the whole file.

PowerShell Blocks Virtual Environment Activation (Windows)

Symptom: Running .venv\Scripts\Activate.ps1 gives a "running scripts is disabled" error.

Fix: Run this command once in PowerShell. Because it changes the setting only for your own account, you don't need to run PowerShell as administrator:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Or use Command Prompt instead: .venv\Scripts\activate (without the .ps1 extension).

"SyntaxError: invalid syntax" on Code That Works for Others

Possible causes: 1. Your Python version is too old for the syntax used (for example, match/case needs 3.10+). Check python3 --version. 2. You're running Python 2 instead of Python 3. Use python3 explicitly. 3. There's a syntax error on the previous line that Python reports on the next line, usually an unclosed bracket or quote. Check the line before the one Python highlights. 4. You copied code from a web page or PDF that swapped in "smart" curly quotes (“ ”) or invisible characters. Retype the quotes by hand.

B.8 Getting Help

When you're stuck:

1. Read the error message carefully. Python's error messages have improved dramatically in recent versions. The traceback tells you the file, line number, and type of error.

2. Search the error message. Copy the last line of the traceback (e.g., TypeError: can only concatenate str (not "int") to str) and search for it. Someone has had this exact problem before.

3. Use the REPL. If you're unsure how something works, test it interactively: ``` python3

   "hello".split() ['hello'] ```

4. Check the official documentation. docs.python.org/3/ is comprehensive and well-written. The Library Reference and Tutorial sections are particularly useful.

5. Ask for help effectively. When asking an instructor, TA, or posting on a forum, include: - What you're trying to do (not just "it doesn't work") - The complete error message (copy-paste, don't paraphrase) - The relevant code (minimal — strip out unrelated parts) - What you've already tried

This guide was written for Python 3.13+ and VS Code as of 2026. Software installation procedures change over time; if these instructions don't match what you see, check the official websites for updated instructions.