Jan 26, 2026
# Chapter 1 — Installation, Setup, and a Clean Workflow
## 1.1 What You Need (Simple List)
- Python 3.11+ (3.10+ is fine too)
- A code editor (VS Code is common, but any editor works)
- A terminal (PowerShell on Windows, Terminal on macOS, bash/zsh on Linux)
## 1.2 Install Python
### Windows
1. Download Python from the official Python website.
2. During install, turn on the option that adds Python to PATH.
3. Finish install.
### macOS
- If you already have Python 3 from `brew`, that is fine.
- Avoid mixing system Python with your project Python.
### Linux
- Use your package manager, or install from Python’s official sources if you need a newer version.
## 1.3 Verify Installation (Your First Terminal Check)
Run:
```bash
python --version
python -m pip --version
```
If `python` does not work on Windows, try:
```bash
py --version
py -m pip --version
```
## 1.3.1 Why `python -m pip` is safer than `pip`
Sometimes your computer has multiple Pythons.
`python -m pip` means: “use the pip that belongs to this python”.
### Diagram: Two Pythons Problem
```text
python (A) -> pip (A) -> installs into A
python (B) -> pip (B) -> installs into B
If you run only "pip", you might accidentally use pip (A) with python (B).
python -m pip keeps them matched.
```
## 1.4 Virtual Environments (Why Everyone Uses Them)
Think of a virtual environment as a separate “toolbox” for one project.
It prevents one project’s packages from messing with another project.
Create and activate:
```bash
python -m venv .venv
```
Windows PowerShell:
```bash
.venvScriptsActivate.ps1
```
macOS/Linux:
```bash
source .venv/bin/activate
```
Install packages inside the environment:
```bash
python -m pip install requests
python -m pip freeze
```
## 1.5 Your Folder Layout (A Good Default)
Make your project look like this:
```text
my_project/
.venv/
src/
main.py
tests/
test_main.py
```
### Diagram: “Where Things Live”
```text
You (terminal)
|
+--> activate .venv (your project toolbox)
|
+--> run python (uses packages from this project)
|
+--> your code in src/
```
---
