Required Setup (DO THIS FIRST)

Everything in this bootcamp runs in a Unix terminal. macOS and Linux already have one. Windows does not, so on Windows you install WSL (Windows Subsystem for Linux), a feature that runs a real Ubuntu system inside Windows.

Why we force this: ML work runs on servers, containers and cloud machines, and those run Linux. Learning the Windows shell now means relearning everything later. Do it once, do it right. On Windows this is done in WSL, not PowerShell!

By the end of this setup you will be able to:

  • Open a Unix terminal on your own machine
  • Install software from that terminal with the uv package manager
  • Run python3 and confirm the version
  • Edit files in VS Code with a terminal attached to the same folder

Step 1 is where the operating systems differ most, and Steps 2, 5 and 6 carry a few lines for one system only. After setup, Windows, Linux and macOS take the same commands almost everywhere.

Step 1. Get a Unix terminal

If on Windows: install WSL

  1. Press the Windows key, type PowerShell, right-click Windows PowerShell, choose Run as administrator. Step 1 is the only time you run PowerShell as administrator.
  2. Run:
wsl --install

There's a chance you might get this in your PowerShell:

wsl: WSL installation appears to be corrupted (Error code: Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG).
Press any key to repair WSL, or CTRL-C to cancel.
This prompt will time out in 60 seconds.

Just press any key on your keyboard.

Once installed, this has turned on the Windows features WSL needs and installed WSL itself with Ubuntu, its default Linux.

  1. Reboot your PC. Not optional. Those features only activate on restart.
  2. After the reboot, open PowerShell as administrator again and make sure WSL 2 is the default:
wsl --set-default-version 2
wsl --status

WSL 1 is the old version, and file-heavy work inside Linux, a git clone (downloading a copy of a project) or an install, runs several times slower on it. We use WSL 2. Always.

Once confirmed, check that a distro (short for distribution, one packaged version of Linux) is installed, which wsl --install normally takes care of with Ubuntu. In the same administrator PowerShell:

wsl -l -v

If it answers Windows Subsystem for Linux has no installed distributions., install Ubuntu, the most common and reliable choice, in the same administrator PowerShell:

wsl --install -d Ubuntu
  1. Press the Windows key, type Ubuntu, open it. First launch takes a minute or two while it unpacks the file system. This happens once.
  2. It asks for a UNIX username. Lowercase, no spaces (goku, not Goku Saiyan). This is your Linux user, unrelated to your Windows account.
  3. It asks for a password, twice.

The password is invisible while you type it. No dots, no stars, no cursor movement. This is normal Unix behavior, not a frozen terminal. Type it, Enter, type it again, Enter.

Write that password down. You type it whenever sudo (as in superuser do, the command that runs something with admin rights) asks for it.

wsl --shutdown is your reset button. When WSL misbehaves, shut it down and reopen Ubuntu.

If on macOS: open Terminal

Press ⌘ Command + Space, type Terminal, press Enter. That is it, you already have a Unix shell.

One thing to install first, because Homebrew, MacPorts and git all need it. Apple's command line tools:

xcode-select --install

A dialog appears, click Install, wait for it to finish. If it says the tools are already installed, move on to Homebrew, or to MacPorts on an Intel Mac.

Then install Homebrew, a package manager for macOS (a tool that downloads and installs other programs for you), which Lesson 0.1.3 uses to install tree. Its installer runs on Apple Silicon Macs only (a Mac with Apple's own chip rather than an Intel one):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

It may ask for your Mac password, invisible as you type it, and it waits for Enter before it installs anything. When it finishes, run the commands it prints under Next steps, then check that brew --version prints a version number.

On an Intel Mac, that installer stops before it installs anything. Homebrew lists every Intel Mac as not supported and recommends moving to a different tool, and the one its support page names for Intel Macs is MacPorts, another package manager for macOS. Install it with the installer for your macOS version from the MacPorts guide, open a new Terminal, and check that port version prints a version number.

If on Linux: you already have one

Press Ctrl + Alt + T, or open your app menu and search for Terminal. Nothing to install. Every Linux command in this bootcamp is written for Ubuntu, so on a distro not built on Ubuntu, swap each apt line for your own package manager's.

From here on, every command runs in that Unix terminal. Windows users: that means the Ubuntu window. PowerShell comes back only for wsl --shutdown, the WSL reset Steps 5 and 6 use.

Your prompt looks roughly like this:

goku@machine:~$

~ means your home directory (/home/goku on Linux and WSL, /Users/goku on macOS).

Terminal survival notes

  • Paste with right-click in the Ubuntu window on Windows, Ctrl + Shift + V on Linux, or ⌘ Command + V on macOS.
  • If a command runs forever or the terminal seems stuck, press Ctrl + C to kill it and get your prompt back. On macOS it is ⌃ Control + C too, because ⌘ Command + C only copies. On Windows, a first Ctrl + C while text is highlighted only copies it, so press it again.
  • If that fails, close the window and open a new terminal.
  • On Windows, if the new Ubuntu window is stuck too, run wsl --shutdown in PowerShell, the reset button from Step 1.
  • If nothing responds at all, restart the computer from its menu. A restart ends every running program, and every file you saved in your home directory is still there afterwards. Hold the power button only when the menu is frozen too, because cutting the power can lose a save from the last few seconds.
  • clear empties a cluttered window, and on Linux, WSL and macOS 14 or later the output you could scroll back to goes too. It uninstalls nothing and changes no file.

Step 2. Install uv

uv is a Python package and project manager written in Rust, built by Astral. One tool replaces four tools you would otherwise install separately: pip (installs packages), venv (creates virtual environments), pyenv (installs and switches Python versions), and pipx (runs standalone command-line tools).

Speed is the headline: roughly 10-100x faster than pip at resolving and installing dependencies, and about 80x faster than python3 -m venv at creating a virtual environment. The bigger win for you is that it installs Python itself, so this setup step becomes one command on every operating system instead of a different package manager per distro.

Older tutorials type pip install everywhere, and Lesson 1.7.3 teaches pip too, inside an environment built to hold it. Here uv does the two jobs pip cannot, installing Python itself and building your environment.

Linux and WSL (Windows users, this means inside your Ubuntu window):

sudo apt update && sudo apt install -y curl  # curl fetches files over HTTP, a fresh Ubuntu may not have it
curl -LsSf https://astral.sh/uv/install.sh | sh

macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close your terminal and open a new one. The installer adds uv to your PATH (the list of folders your shell searches for every command you type), and your current shell will not see it until it restarts. This is the number one "I installed it but uv: command not found" cause. Then verify:

uv --version

A version number means the install passed.

Step 3. Install Python with uv

Install Python:

uv python install 3.12.8  # downloads CPython 3.12.8, the standard Python

Install the exact patch version, 3.12.8, not just 3.12. The patch is the last of the three numbers. Asking for 3.12 gives you whatever the newest 3.12.x happens to be on the day you run it. The bootcamp is written and validated against 3.12.8, and every printed result in every lesson came from that interpreter (the program that reads and runs Python code). Pinning the patch is how your output matches the lesson's output character for character.

Important, and it surprises everyone once: uv puts this Python on your PATH under its versioned name only, so python3.12 works from any folder while a bare python3 may still point at your system Python or at nothing at all. You do not fix this by installing Python a second time. You fix it by creating a virtual environment, which is Step 4, and which you should be doing anyway.

Check what uv knows about:

uv python list  # every Python uv can see, plus the newest download of each version

DON'T:

  • DON'T mix package managers. If you installed Python with uv, do not also apt install python3 or brew install python to "make it work". You will end up with several interpreters and no idea which one your code ran on. That confusion is a real bug class, not a beginner mistake.
  • DON'T install packages system-wide. On modern Ubuntu and Homebrew, a global pip install is blocked on purpose (the externally-managed-environment error). Everything goes in a virtual environment.
  • DON'T type python. The command is python3, and inside an activated environment it is the one you created.

Step 4. Create your project folder and virtual environment

What. A virtual environment is a private folder that points at one Python interpreter and holds one set of packages, belonging to one project. Its name here is .venv, and the dot means the file manager hides it by default.

Why. Project A needs pandas 2.2 and project B needs pandas 3.0. Installed globally, one of them breaks. Given one environment each, neither ever sees the other. This is not optional hygiene, it is how Python projects work.

When. Right after a project's folder exists and before its first package goes in, which for this folder is now.

mkdir -p ~/dev/bootcamp  # dev as in development, -p creates parent folders as needed
cd ~/dev/bootcamp        # cd as in change directory: move into it
uv venv --python 3.12.8  # create the environment using the exact version you just installed
uv python pin 3.12.8     # write .python-version so uv here always picks 3.12.8

uv python pin creates a small file called .python-version in the folder. Any uv command run here from now on reads that file and uses 3.12.8, even if you install other versions later. Keep that file with the project, it is how your machine and everyone else's agree on the interpreter.

uv venv printed a line telling you how to activate it. Activate it now:

source .venv/bin/activate

Your prompt changes and now starts with (bootcamp), the name of the folder the environment lives in:

(bootcamp) goku@machine:~/dev/bootcamp$

That prefix is the entire point. If it is not there, assume you are not in the environment, and check with which python3 before you trust python3. When a command mysteriously fails, look at your prompt first.

Inside an activated environment, python3 resolves to the one in .venv. So every python3 you type with (bootcamp) active runs the interpreter you just built.

Confirm it:

python3 --version  # Python 3.12.8
which python3      # a path ending in /dev/bootcamp/.venv/bin/python3

If which python3 prints any other path, /usr/bin/python3 for one, the environment is not active. Run the source line again.

To leave the environment:

deactivate

You activate the environment every time you open a new terminal. It does not persist. Get used to cd ~/dev/bootcamp && source .venv/bin/activate as one muscle-memory move. Once Step 6 installs the Python extension, every new VS Code terminal runs the activation for you.

Step 5. Install Visual Studio Code

VS Code is where you write your .py files. It is free. Download it from the official download page and install it.

  • If on Windows: Install VS Code on WINDOWS, not inside Ubuntu. This trips up everybody once. VS Code runs as a normal Windows app and reaches into Ubuntu to edit the files. You do NOT install it with apt. Install it from the official website. During installation, leave "Add to PATH" checked, and on the GitHub Copilot CLI page choose Don't add the copilot command.
  • If on macOS: drag the app into /Applications, open it, then press ⌘ Command + Shift + P, type shell command, and run Shell Command: Install 'code' and optionally 'copilot' commands in PATH, which reads Shell Command: Install 'code' command in PATH when AI features are switched off. When it asks whether to also install GitHub Copilot CLI, answer No. Without that command, code does not work in Terminal.
  • If on Linux: install the .deb or .rpm from the site, or the official Snap, an app package format many distros can install, with sudo snap install --classic code. Each adds the code command for you. Skip any other build your software store or distro offers, such as a Flatpak, another app package format, or Arch's own code package, because the Flatpak runs its terminal in a sandbox apart from your system and Arch's open-source build cannot install Pylance (the code checker the Python extension brings with it).

IMPORTANT

  1. If on Windows, install the WSL extension from the Extensions panel (Ctrl + Shift + X, search WSL, by Microsoft). It is what lets VS Code on Windows edit files and run a terminal inside Ubuntu.
  2. If on Windows, restart WSL now. Open PowerShell and run:
wsl --shutdown

Then open Ubuntu again from the Start menu. A shell in Ubuntu copies the Windows PATH once, at the moment it opens, from the program that opens it, so an Ubuntu window that was already open while VS Code installed never learns where code lives. wsl --shutdown ends every Ubuntu shell at once, so the window you open next is certain to be new. Keep typing in a window from before the install and the next step fails with Command 'code' not found even though "Add to PATH" was checked.

  1. Do NOT install the Python extension yet, on any OS. On Windows it has to live inside Ubuntu, and the Ubuntu side of VS Code does not exist until Step 6 opens it. Installing it now puts it on the Windows side, where it is useless to you, and it can leave the Extensions panel spinning on Installing forever later. Step 6 says exactly when and how.

Step 6. Open the folder in VS Code

In a fresh terminal (on macOS and Linux a new Terminal window, on Windows the Ubuntu window you just reopened after wsl --shutdown):

cd ~/dev/bootcamp
source .venv/bin/activate
code .  # open VS Code in the current folder (the . means "here")

Windows users: the first code . installs a small server inside Ubuntu, and after each VS Code update the next code . replaces it, printing Updating VS Code Server to version and a long ID. VS Code opens with WSL: Ubuntu in the bottom-left corner. That label is the whole point, the editor runs on Windows while the files, the terminal, and Python all live on the Linux side.

If code . answers Command 'code' not found (on macOS, zsh: command not found: code):

  • Windows. Check the two usual causes in order. First, the Ubuntu window you typed in was open before VS Code installed (Step 5, IMPORTANT, item 2). Run wsl --shutdown in PowerShell, open Ubuntu again from the Start menu, try again. Second, the installer ran without Add to PATH checked, so rerun the installer with it checked, then wsl --shutdown again. Do NOT edit PATH inside Ubuntu, do NOT apt install code, and do NOT add code to .bashrc, none of that is the problem. While you sort it out, the other door works: open VS Code on Windows, Ctrl + Shift + P, WSL: Connect to WSL, then File > Open Folder and type /home/goku/dev/bootcamp.
  • macOS. You skipped the Shell Command step in Step 5. Run it, open a new Terminal, try again.

Trust the folder. A folder you open for the first time starts in Restricted Mode: a banner across the top says so, and the status bar at the bottom shows Restricted Mode. VS Code asks whether you trust the folder, either as it opens or the first time you open its terminal:

Do you trust the authors of the files in this folder?

Trust it, with Trust Folder & Continue or Yes, I trust the authors, whichever button your dialog shows. Same answer on every operating system.

What. Workspace Trust is a VS Code safety feature. Until you trust a folder, VS Code keeps it in Restricted Mode, which asks before a terminal, a task or the debugger runs, and disables extensions that could execute code from that folder, the Python extension among them.

Why. Opening a project you downloaded from the internet can run code before you have read a single line of it. Restricted Mode is the seatbelt for that.

When. Trust folders you created yourself and repositories you actually reviewed. Clone a random repo off the internet and you open it in Restricted Mode first, then read it.

You created this folder yourself, so trusting it is correct. If you dismissed the dialog and nothing runs, click Restricted Mode in the bottom status bar and trust it from there.

Windows only: keep your project files in ~/dev/, inside Linux. Do not work out of /mnt/c/Users/... (your Windows drive as seen from Linux). File access across that boundary is slow and permissions get strange.

Open the built-in terminal with Ctrl + ` (backtick), the same key on macOS, where it is ⌃ Control + `, not ⌘ Command. It opens a shell already sitting in your project folder. That is the terminal you use from now on.

Crucial: install the Python extension, from that terminal, NOW. VS Code colors Python code on its own, and the extension adds error squiggles, autocompletion and the interpreter picker used below. Do it with a command, not with the Extensions panel:

code --install-extension ms-python.python

Same command on every operating system. It downloads four extensions (Python, Pylance, the debugger, the environment manager), checks their signatures, and takes about a minute. Windows users: the code inside this terminal is the Ubuntu-side one, so the extension lands inside Ubuntu, next to your files and your Python, which is where it has to be. code run from a plain Windows PowerShell would put it on the Windows side instead, and a Windows-side copy does nothing for a WSL: Ubuntu window.

Why not the panel. Clicking Install in WSL: Ubuntu in the Extensions panel can sit on Installing for hours with no error shown anywhere. This is a real VS Code failure, not something you did wrong. The command asks for the same install, but it prints every step in the terminal, so a stall shows itself, and the Windows retry below goes around the VS Code window altogether.

If the command prints Installing extension 'ms-python.python'... and then nothing for two minutes, it is waiting on a Marketplace request that will never answer. Do not wait it out. Press Ctrl + C, then retry, and the retry is different per OS:

  • macOS and Linux: run the same command again. Each run is a fresh attempt, the second or third goes through in seconds.

  • Windows: do NOT run the same command again. The code in this terminal hands the job to the VS Code window, which passes it to VS Code's server inside Ubuntu, so Ctrl + C stops the hand-off but the stuck attempt keeps living inside that server, and a second code --install-extension just joins the stuck attempt and waits with it (so does Developer: Reload Window). Retry with the server's own installer instead, which starts fresh every time:

    ~/.vscode-server/bin/*/bin/code-server --install-extension ms-python.python

    Same output, apart from a two-line DeprecationWarning from Node (the engine the server runs on) that you can ignore, and the same one-minute duration. If this one also goes quiet for two minutes, Ctrl + C and run it again, this one you can repeat. It works from any Ubuntu terminal, VS Code open or not.

Confirm it landed:

code --list-extensions

You want ms-python.python somewhere in that list (Windows users also see the heading Extensions installed on WSL: Ubuntu: above it, that heading is the proof it went to the right side). If the Extensions panel still shows Installing after the command finished, press Ctrl + Shift + P, type Developer: Reload Window, and press Enter.

Two more extensions, and the ones to leave alone

Besides the WSL extension on Windows, the Python extension is the only one you need. These two are cheap, do one job each, and that job comes up in Module 0 already. Install them the same way, in the same terminal, one command:

code --install-extension mechatroner.rainbow-csv --install-extension oderwat.indent-rainbow

Takes a few seconds. Same stall rule as above: Ctrl + C, then retry, Windows users retry through ~/.vscode-server/bin/*/bin/code-server with the same two --install-extension arguments.

  • Rainbow CSV (mechatroner.rainbow-csv). Most tables in this bootcamp are .csv files, from Module 0's first data files to Module 2's housing set, and you will open them in VS Code to look at them. Raw, a CSV is a wall of commas and you cannot tell which value belongs to which column past the third one. This colors each column differently and shows the column name when you hover a value. Nothing to configure, it switches on the moment you open a .csv.
  • indent-rainbow (oderwat.indent-rainbow). In Python, indentation IS the program: a line four spaces in belongs to the if above it, and a line two spaces in, under a block indented four, matches no level and is an IndentationError. This shades each indentation level a different color, so a line at the wrong depth looks wrong before you run it. IndentationError, whose messages include unexpected indent, is among the commonest errors in Module 1, and most of them become visible with this on.

Confirm both landed with code --list-extensions again, you now want six IDs: the four ms-python.* ones plus these two.

Do NOT install these, however popular they are:

  • Code Runner. Its Run button starts your file with a bare python found through VS Code's own PATH, which is the .venv one only when VS Code was opened with code . from a (bootcamp) terminal. When VS Code is opened any other way, the Run button finds no python at all, or one that raises ModuleNotFoundError for packages you installed a minute ago, and you spend an hour on a problem that does not exist. Run scripts the way the bootcamp says, python3 file.py in the terminal with (bootcamp) in the prompt.
  • Jupyter. This bootcamp is scripts, not notebooks, on purpose. A notebook lets cells run out of order, so a program can appear to work and then break when run top to bottom. Learn on scripts, and notebooks will make sense faster for it whenever you pick them up.
  • GitLens, GitHub Pull Requests, any git GUI. Module 0 Section 3 teaches git at the command line because the commands are the concepts. A button that runs three of them for you hides which three. VS Code's built-in Source Control view (the branch icon on the left) already shows changed files and lets you commit, and that is the most GUI you use here.
  • GitHub Copilot or any AI autocomplete. Not during the bootcamp. VS Code ships with Copilot built in, and it suggests nothing until you sign in to it, so do not sign in, and switch it off: open Settings with Ctrl + , (⌘ Command + , on macOS), search chat.disableAIFeatures, and tick its box. It writes the line before you have thought the line, and the whole point of the bootcamp is that you can think the line. Turn it on after.
  • Themes, icon packs, bracket colorizers. Bracket pair coloring is built into VS Code already. The rest is decoration, install it on your own time, not in setup.

Point VS Code at your environment

A (bootcamp) prefix in the terminal means the shell is in the environment, but VS Code itself picks its interpreter separately. It picks the .venv inside the folder on its own, so this is a check: press Ctrl + Shift + P (⌘ Command + Shift + P on macOS), run Python: Select Interpreter, and make sure the one ending in .venv/bin/python is selected, NOT /usr/bin/python3. Do this once per project. With any other interpreter selected, VS Code checks and runs your code against that one and reports imports as missing when they are installed fine.

Once done, the bottom-right corner of VS Code shows something like bootcamp (3.12.8), and hovering it shows a path ending in .venv/bin/python.

Run a script

To run a Python file (a script), create it inside your project folder: in VS Code's Explorer panel on the left, hover over the folder's name, click the New File icon, and give the file a name ending in .py, because the .py extension is what marks it as a Python file. Write one line in it, print("training rows:", 120), and save it with Ctrl + S (⌘ Command + S on macOS). Then, in VS Code's built-in terminal from Step 6, check that the prompt shows (bootcamp), run source .venv/bin/activate if it does not, and type python3 followed by the file's name:

python3 file0.py  # file0.py stands for whatever you named the file

It prints training rows: 120.

Setup checklist (pass ALL of these before Lesson 0.1.1)

Open a fresh terminal, then run:

cd ~/dev/bootcamp
source .venv/bin/activate

whoami             # prints your Unix username
pwd                # prints /home/goku/dev/bootcamp (macOS: /Users/goku/dev/bootcamp)
uv --version       # prints a uv version
python3 --version  # prints Python 3.12.8 exactly
which python3      # path ends in /dev/bootcamp/.venv/bin/python3
uname -s           # prints Linux on Linux and WSL, Darwin on macOS
# prints 3 (run this one in VS Code's own terminal)
code --list-extensions | grep -c -E "ms-python.python|rainbow-csv|indent-rainbow"

Windows users, one extra:

uname -r  # must contain microsoft-standard-WSL2, proving you are in WSL and not somewhere else

macOS users, one extra, for your kind of Mac:

brew --version  # Apple Silicon: prints Homebrew and a version number
port version    # Intel: prints Version: and a version number

Your prompt must show (bootcamp) the whole time. If any line fails, fix it now. Do not continue to the lesson until all of them pass. No exceptions.

Setup is not busywork. A broken environment fails in ways that look exactly like broken code, and you cannot debug your machine and your program at the same time.