---
title: "Setup — from a fresh computer to a working installation"
sidebar:
  label: "Setup"
---

<span id="setup-from-a-fresh-computer-to-a-working-installation" />


[Course home](/) · [Learning guide](/learning-guide) · [→ Unit 0](/unit-00)

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 [#1-get-python-git-and-an-editor]

Install Python 3.11 or newer and Git if they are missing:

- **Windows:** Python from [python.org](https://www.python.org/downloads/) (tick
  the installer's "Add python.exe to PATH" option) and Git from
  [git-scm.com](https://git-scm.com/downloads).
- **macOS:** Python from [python.org](https://www.python.org/downloads/). The
  first `git --version` below 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 git` and check
  that `python3 --version` shows 3.11 or newer. Without `python3-venv`, step 3
  fails with `ensurepip is not available`.

Open Terminal (macOS/Linux) or PowerShell (Windows), then check:

```bash
python3 --version
git --version
```

On 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](https://code.visualstudio.com/) (free, all systems). Do not use
TextEdit or Word: they save formatting that Python cannot read.

## 2. Get the course [#2-get-the-course]

```bash
git clone https://github.com/minigraphx/llm-engineering-course.git
cd llm-engineering-course
```

During 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`.

<aside className="course-note" aria-label="Getting access: if the repository is private for you">
<strong>Getting access: if the repository is private for you</strong>

`git clone` then asks for a username and password, and GitHub no longer
accepts your account password there. First accept the invitation e-mail from
GitHub. Then pick one way in:

- **GitHub CLI:** install [gh](https://cli.github.com/), then run
  `gh auth login --web --git-protocol https`. It shows a one-time code and
  opens the browser: press Enter, paste the code, authorise. Then clone with
  `gh repo clone minigraphx/llm-engineering-course`.
- **GitHub Desktop:** install [GitHub Desktop](https://desktop.github.com/),
  sign in, and use File → Clone repository.
- **ZIP:** on the repository page choose Code → Download ZIP and unpack it.
  Rename the unpacked folder `llm-engineering-course-main` to
  `llm-engineering-course`, so every later instruction works unchanged.


</aside>

**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 [#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:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,docs]"
```

<details>
<summary>Linux without an NVIDIA GPU</summary>

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:

```bash
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]"
```


</details>

Windows PowerShell:

```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 [#every-session]

Each time you open a new terminal:

1. Go to the course folder: `cd llm-engineering-course` (the VS Code terminal
   already starts there).
2. Activate the environment: `source .venv/bin/activate` on macOS/Linux,
   `.\.venv\Scripts\Activate.ps1` in Windows PowerShell.
3. Check that the prompt now starts with `(.venv)`. Without it, `python` may be
   a different Python that lacks the course libraries.

### Read when a lesson first needs it [#read-when-a-lesson-first-needs-it]

Skip these today; lessons link back here when they need them.

<details>
<summary>Tokenizer table: internet needed once</summary>

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.


</details>

#### Shell conventions for all lessons [#shell-conventions]

<details>
<summary>Full paths, heredoc blocks and PowerShell</summary>

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:

1. Create the folder with `python -c "from pathlib import Path; Path('artifacts/my-work').mkdir(parents=True, exist_ok=True)"`.
2. Copy only the Python lines between `python - <<'PY'` and the final `PY` into
   `artifacts/my-work/check.py` using your editor. Do not copy either marker or the
   Markdown backticks. Save the file.
3. Run `python artifacts/my-work/check.py` from 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.


</details>

## 4. Check the installation [#4-check-the-installation]

```bash
python examples/check_device.py
python examples/diagnose_unit0.py
```

Every check should say `pass` and `ready` should say `yes`; [Unit 0](/unit-00)
explains each line.

## 5. Check the course and open the lessons [#5-check-the-course-and-open-the-lessons]

```bash
python -m pytest
python -m mkdocs build --strict
```

The 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](/learning-guide), then Unit 0.

## If something fails [#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](/unit-00-troubleshooting)
and [hardware profiles](/hardware).
