Setup — from a fresh computer to a working installation
Course home · Learning guide · → Unit 0
Allow 20–40 minutes for the first installation. A terminal is a window where
commands run; a repository is the course folder plus its change history.
Commands in this course run from that folder. Copy only the command, without a
leading $ or >>>. Python code blocks go into a .py file, not the terminal.
1. Get Python, Git and an editor
Install Python 3.11 or newer and Git if they are missing:
- Windows: Python from python.org (tick the installer’s “Add python.exe to PATH” option) and Git from git-scm.com.
- macOS: Python from python.org. The
first
git --versionbelow opens a dialog offering the Command Line Tools; choose Install, wait 5–15 minutes, then run it again. - Ubuntu/Debian: Ubuntu 24.04 / Debian 12 or newer (older releases ship a
Python below 3.11). Run
sudo apt install python3 python3-venv gitand check thatpython3 --versionshows 3.11 or newer. Withoutpython3-venv, step 3 fails withensurepip is not available.
Open Terminal (macOS/Linux) or PowerShell (Windows), then check:
python3 --version
git --versionOn Windows use py --version. If neither Python command works, finish installing
Python and reopen the terminal. A CPU is sufficient; no GPU or cloud account is
needed. Installation downloads dependencies; the required new training labs
then run offline.
Editor: lessons ask you to save small .py files. Install
VS Code (free, all systems). Do not use
TextEdit or Word: they save formatting that Python cannot read.
2. Get the course
git clone https://github.com/minigraphx/llm-engineering-course.git
cd llm-engineering-courseDuring the private pilot you need access to this GitHub repository. A Repository not found message can mean missing access, not a broken Python installation.
If you already have the course folder, open a terminal there and skip cloning.
The folder should contain README.md, pyproject.toml, examples, and src.
Open the folder in VS Code: File → Open Folder… and choose
llm-engineering-course. Terminal → New Terminal opens a terminal that already
starts in the course folder; use it for every command in the course.
3. Create an isolated Python environment
A virtual environment keeps the course libraries separate from other projects. Create it once; activate it again in every new terminal.
The install needs about 1 GB of disk, most of it PyTorch.
macOS/Linux:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,docs]"Linux without an NVIDIA GPU
On Linux the default PyTorch download is about 2 GB of NVIDIA (CUDA) libraries the course does not need. Use these lines instead of the block above to get the 190 MB CPU build:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install -e ".[dev,docs]"Windows PowerShell:
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,docs]"If PowerShell blocks activation, run .\.venv\Scripts\python.exe instead of
python; activation is a convenience and is not required. Use
.\.venv\Scripts\python.exe -m pip install -e ".[dev,docs]" in that case.
On macOS/Linux the equivalent full interpreter path is .venv/bin/python.
-e makes edits to the course package immediately available; dev,docs adds
testing and documentation tools. Wait until installation finishes successfully.
Every session
Each time you open a new terminal:
- Go to the course folder:
cd llm-engineering-course(the VS Code terminal already starts there). - Activate the environment:
source .venv/bin/activateon macOS/Linux,.\.venv\Scripts\Activate.ps1in Windows PowerShell. - Check that the prompt now starts with
(.venv). Without it,pythonmay be a different Python that lacks the course libraries.
Read when a lesson first needs it
Skip these today; lessons link back here when they need them.
Tokenizer table: internet needed once
The first full test run or byte-pair-encoding (BPE) comparison may need internet
once: the pre-existing tokenizer lab loads the public cl100k_base encoding table
and caches it locally. Installing the Python packages does not pre-cache that
table. The mandatory T05/T06 and E01–E04 model, training, evaluation and profiling experiments
use locally generated data and remain offline after installation.
Shell conventions for all lessons
Full paths, heredoc blocks and PowerShell
After activation, use the active python command on every platform. Some older
examples or reference records show full macOS/Linux environment paths:
| Written command | With the environment active, including PowerShell |
|---|---|
.venv/bin/python script.py |
python script.py |
.venv/bin/pytest tests/... |
python -m pytest tests/... |
Blocks beginning with python - <<'PY' use heredoc syntax: Bash/Zsh send the
following Python lines to the interpreter until the closing PY. PowerShell does
not understand that wrapper. The portable alternative works on all platforms:
- Create the folder with
python -c "from pathlib import Path; Path('artifacts/my-work').mkdir(parents=True, exist_ok=True)". - Copy only the Python lines between
python - <<'PY'and the finalPYintoartifacts/my-work/check.pyusing your editor. Do not copy either marker or the Markdown backticks. Save the file. - Run
python artifacts/my-work/check.pyfrom the repository root.
If activation is unavailable on Windows, replace python in these commands with
.\.venv\Scripts\python.exe. The same Python body produces the same result;
only the way the shell passes it to Python changes.
4. Check the installation
python examples/check_device.py
python examples/diagnose_unit0.pyEvery check should say pass and ready should say yes; Unit 0
explains each line.
5. Check the course and open the lessons
python -m pytest
python -m mkdocs build --strictThe first test run may need internet once (see the tokenizer note above). Tests end
with a count line: passed, deselected and warnings are fine; any failed is
not. The docs build must finish without an error.
Optional, only if you want to read the lessons offline instead of on the hosted
site: python -m mkdocs serve prints a local address, usually
http://127.0.0.1:8000; open it in your browser. Press Ctrl+C in the terminal
to stop it. EN/DE switches the lesson language.
Start the learning guide, then Unit 0.
If something fails
| Message or symptom | Check and repair |
|---|---|
git clone asks for a username or password |
The repository is private for you; see Getting access in step 2. |
requires a different Python: 3.10… not in '>=3.11' |
Your Python is older than 3.11. Install 3.11 or newer, delete the .venv folder and repeat step 3. |
ensurepip is not available |
Ubuntu/Debian: run sudo apt install python3-venv, then repeat step 3. |
No such file for an example |
Run from the course folder, after cd llm-engineering-course. |
No module named llm_course |
Use the environment’s Python and repeat the editable install. |
No module named torch |
The environment is not active: activate .venv (see Every session). Otherwise installation did not finish. |
| No output while installing | Large packages can take minutes; wait for completion or an actual error. |
| Accelerator error | Add --device cpu to the lab command. |
Can’t type commands after mkdocs serve |
It is running; open a second terminal or stop with Ctrl+C. |
Record the command and the last error lines when diagnosing a problem. Never paste credentials into a report. More: Unit 0 troubleshooting and hardware profiles.