Module 1 · Getting started

Install, run & set up your tools

Foundations 16 min read A clean setup saves hours of confusion later

You need three things: Python itself, a way to run your files, and virtual environments so each project gets its own set of installed packages. Add a good editor and you have the same setup professional Python developers use. Most early frustration ("it works on my machine", "module not found") comes from skipping the virtual environment step, so this lesson spends time on it.

🧳

One suitcase per trip

Your computer's Python is your home wardrobe. A virtual environment is a suitcase packed for one trip (one project): exactly the packages that project needs, in the versions it needs. Pack a suitcase per project and a beach trip never ends up with ski boots, and two projects never fight over package versions.

1. Install Python

winget install Python.Python.3.14        # or download the installer from python.org
py --version                             # the "py" launcher picks the newest installed Python
python --version

With the python.org installer, tick "Add python.exe to PATH". If typing python opens the Microsoft Store, turn off the "App execution aliases" for python in Windows settings, or just use py.

brew install [email protected]                 # with Homebrew, or use the python.org installer
python3 --version                        # macOS calls it python3; "python" may not exist

python3 --version                        # most distributions ship a Python 3 already
sudo apt install python3 python3-venv    # Debian/Ubuntu: add venv support if missing

Do not remove or upgrade the system Python in place. The operating system's own tools depend on it. Install additional versions alongside it (uv makes this easy).

# install uv: see docs.astral.sh/uv for the one-line installer for your OS
uv python install 3.14                   # installs a Python just for uv-managed projects
uv python list                           # what is installed / available

2. Four ways to run Python code

Command	What it does	Use it for
`python`	opens the interactive REPL (`>>>`)	trying things out
`python hello.py`	runs a file from top to bottom	your programs
`python -m venv .venv`	runs a module as a program	built-in tools: venv, pip, http.server, json.tool
`python -c "print(2**10)"`	runs one line of code	quick checks in scripts

python, python3 or py?

Same program, different names by platform. On Windows use py or python; on macOS and Linux, python3. Inside an activated virtual environment, python always means that environment's Python, which is one more reason to use one.

3. Virtual environments

py -m venv .venv
.venv\Scripts\Activate.ps1               # the prompt now starts with (.venv)
python -m pip install requests
python -m pip freeze > requirements.txt  # record exact versions
deactivate

If PowerShell refuses to run Activate.ps1, its script policy is blocking it. Many developers allow local scripts for their own user with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Check with whoever manages your machine first. Or skip activation and call .venv\Scripts\python.exe directly.

python3 -m venv .venv
source .venv/bin/activate                # the prompt now starts with (.venv)
python -m pip install requests
python -m pip freeze > requirements.txt
deactivate

uv init my-project && cd my-project     # creates pyproject.toml
uv add requests                          # creates .venv, installs, records the version (uv.lock)
uv run main.py                           # runs inside the environment, no activation needed

You can check from inside Python whether you are in a virtual environment: sys.prefix (this environment) differs from sys.base_prefix (the base install). This example creates a throwaway environment and asks its Python:

import subprocess
import sys
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as folder:
    env = Path(folder) / ".venv"
    subprocess.run([sys.executable, "-m", "venv", "--without-pip", str(env)], check=True)
    python = env / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
    check = "import sys; print(sys.prefix != sys.base_prefix)"
    inside = subprocess.run([str(python), "-c", check], capture_output=True, text=True).stdout.strip()
    print("venv folder contains:", sorted(p.name for p in env.iterdir()))   # Windows: Scripts, Lib; else bin, lib
    print("the venv's python says it is in a venv:", inside)
print("this script's python is in a venv:", sys.prefix != sys.base_prefix)

venv folder contains: ['.gitignore', 'Include', 'Lib', 'Scripts', 'pyvenv.cfg'] the venv's python says it is in a venv: True this script's python is in a venv: False

Rules that prevent most setup pain

One .venv per project, inside the project folder. Never commit .venv to Git (add it to .gitignore); commit requirements.txt or pyproject.toml instead. Install with python -m pip so pip belongs to the same Python you run. Never sudo pip install.

4. An editor that helps

VS Code

Install the Python extension, then "Python: Select Interpreter" and pick your .venv. You get autocomplete, error squiggles, a debugger and a run button.

PyCharm

A full Python IDE with excellent refactoring and debugging. The Community edition is free.

Jupyter notebooks

Cells of code with output underneath. Great for data exploration, not for programs. Available in VS Code too.

Turn on format on save with a formatter such as ruff format or Black (lesson 20). You will never think about spacing again.

5. A folder layout for this course

learn-python/
├── .venv/                 ← created by python -m venv .venv (not committed)
├── lessons/
│   ├── 01_hello.py
│   └── 04_numbers.py
├── project/               ← lesson 21
└── requirements.txt

6. Troubleshooting

Symptom	Cause	Fix
`'python' is not recognized`	Python not on PATH	use `py` (Windows), re-run the installer with "Add to PATH", or open a new terminal
`ModuleNotFoundError: No module named 'requests'`	installed into a different Python than the one running	activate the venv; install with `python -m pip`; check the interpreter selected in your editor
Works in the terminal, fails in the editor	the editor uses another interpreter	select the `.venv` interpreter in the editor
Which python is running?	several installs	`python -c "import sys; print(sys.executable)"`, or `where python` / `which python`

Recap

Install Python 3.12+ from python.org, your package manager, winget/brew, or uv.
Run with python file.py; python -m tool runs built-in tools.
One virtual environment per project; install with python -m pip and record versions.
Point your editor at the venv, and most "module not found" mysteries disappear.

Checkpoint

1 · You installed requests, but your script says "No module named 'requests'". Most likely?

Each Python (and each venv) has its own packages. Activate the venv and install with python -m pip so both use the same interpreter.

2 · What should you commit to Git for a project's dependencies?

A venv is machine-specific and large. The dependency list lets anyone recreate it with one command.