Chapter 0: Development Setup (Optional)

cd changes your working directory, ls lists files and folders, pwd prints where you currently are, and ~ is a shortcut for your home directory. These four commands account for the majority of terminal usage in day-to-day development. Use cd - to jump back to the previous directory and ls -la to see hidden files (like .gitignore and .env) along with permissions and file sizes. Getting fast at navigation means you spend less time finding things and more time building.

mkdir -p creates nested directories in one command (e.g., mkdir -p data/raw data/processed). cp -r copies entire folders recursively, mv both moves and renames files, and rm -rf deletes directories and their contents without confirmation — use it carefully. touch creates empty files, which is useful for scaffolding project structures quickly. These commands are the foundation for organizing ML projects: creating data directories, moving model checkpoints, and cleaning up experiment outputs.

cat dumps an entire file to your terminal, which works for short files but floods your screen for long ones. head -20 file.txt shows the first 20 lines and tail -20 file.txt shows the last 20 — perfect for checking CSV headers or the end of a training log. less opens a scrollable viewer where you can search with /pattern and quit with q. For ML work, you'll frequently use tail -f logs/training.log to watch training progress update in real time.

grep finds text patterns inside files — grep -rn 'learning_rate' src/ searches recursively and shows line numbers, which is invaluable for finding where hyperparameters are set in a large codebase. find locates files by name or attributes: find . -name '*.py' -mtime -1 finds all Python files modified in the last day. which python tells you the exact path of the Python binary that will run when you type python, which is critical for debugging virtual environment issues.

The pipe operator | sends the output of one command as input to another, letting you chain simple tools into powerful workflows. For example, cat train_log.txt | grep 'epoch' | tail -5 extracts the last 5 epoch results from a training log. > writes output to a file (overwriting it), while >> appends without erasing existing content. These operators are the backbone of shell scripting — once you're comfortable composing commands with pipes, you can process logs, filter datasets, and automate reporting without writing Python scripts.

A consistent layout lets you, your collaborators, and your tools find things without asking. This step builds one in a few commands. mkdir -p creates a directory together with any missing parents and does not complain if it already exists, so the command is safe to rerun. Brace expansion, as in src/{data,models,utils}, is done by the shell before mkdir runs, so one line creates three folders. touch creates empty files. An empty __init__.py marks a folder as a Python package so from src.data import dataset works. Brace expansion needs no spaces after the commas, or the shell treats the braces literally.

Once the tree exists, you fill it with content and practice finding things in it, the two tasks behind most terminal work. A heredoc, cat > file << 'EOF', writes every line up to the closing EOF into the file in one command, and quoting 'EOF' stops the shell from expanding variables inside the text. find . -name "*.py" lists files by pattern. Piping that list into wc -l counts them, and grep searches inside files, as in the Searching concept above. A single > overwrites the target file, so writing .gitignore twice with > keeps only the second version.

The final step combines everything. A pipe feeds one command's output into the next, so listing, filtering, and counting Python files becomes one line. A single > saves output to a file, replacing its contents, while a double >> appends to it, which is how you keep a growing log. du -sh reports how much disk each folder uses, which helps when datasets or checkpoints fill a drive. export sets an environment variable that programs started from this shell inherit. A trailing ampersand starts a command in the background, jobs lists background tasks, and fg brings one back. Background jobs still stop when the terminal closes.

Download VS Code from code.visualstudio.com — always use the official site to get the latest stable release. On Ubuntu, download the .deb file and install with sudo dpkg -i code_*.deb, which also sets up the code terminal command automatically. On macOS, drag the .app to Applications, then open VS Code and run "Shell Command: Install 'code' command in PATH" from the command palette. After installation, typing code . in any terminal opens that folder as a VS Code workspace.

The Python extension (Microsoft) provides IntelliSense, debugging, and virtual environment detection. Pylance adds fast type checking and auto-imports that catch errors before you run your code. The Jupyter extension lets you run .ipynb notebooks directly in VS Code without a separate server. GitLens annotates each line with its last commit, making it easy to track when and why code changed. Docker and Remote-SSH extensions are optional but become essential when you start deploying models or working on remote GPU servers.

VS Code's defaults suit general editing, and three changes remove most of the friction for Python ML work. files.autoSave set to afterDelay saves about a second after you stop typing, so a script you run from the Terminal & Command Line never uses stale code. editor.formatOnSave runs a formatter such as Black or Ruff on every save, so style stays consistent without effort. python.defaultInterpreterPath set to .venv/bin/python makes linting, completion, and the Run button use your project's virtual environment. If that path is wrong, imports that work in the terminal show red squiggles in the editor. Workspace settings override user settings for one project.

Ctrl+P (Quick Open) is the single most useful shortcut — it lets you jump to any file by typing part of its name, far faster than clicking through folders. Ctrl+Shift+P opens the Command Palette where you can search for any VS Code action (change theme, restart Python, format document). Ctrl+\`` toggles the integrated terminal so you can run scripts without leaving the editor. Ctrl+D` selects the next occurrence of your highlighted text for multi-cursor editing, which is perfect for renaming variables across a function.

The Remote-SSH extension connects VS Code to a remote machine over SSH, so you edit files locally with full IntelliSense and extensions while code executes on the remote GPU server. This is a game-changer for ML — you get the comfort of your local editor with the compute power of a cloud instance. Set up your SSH config with a named host (Host gpu-server) for one-click connections. Skip this if you're working locally; it becomes relevant when you need to train on machines with GPUs you don't have on your laptop.

Install the editor from the official site, then add extensions from the terminal instead of clicking through the marketplace. code --install-extension <id> installs one extension by its identifier, such as ms-python.python, which makes the setup scriptable and repeatable on a new machine. The seven extensions cover Python language support and Pylance type checking, notebooks, Git history, Remote-SSH, Docker, and an AI assistant. The final command lists what is installed so you can confirm each one. If code is not found, the launcher is not on your PATH. On macOS, run the Shell Command action from the Command Palette described in Installation.

This step writes the settings described above into settings.json in one command. That file is the source of truth behind the graphical Settings screen, so anything you set in the screen appears there as JSON. Auto-save, format-on-save, and the virtual-environment interpreter are the important lines. The rest set fonts, word wrap, and the color theme. The path shown, ~/.config/Code/User/settings.json, is the Linux location. macOS keeps the file under ~/Library/Application Support/Code/User/. Writing it with a single > replaces any existing settings, so merge by hand if you already have some. A stray trailing comma makes VS Code report the file as invalid.

When the GPU lives on a server, editing over SSH with a terminal editor is slow and error-prone. Remote-SSH fixes that. The step first adds a named host to ~/.ssh/config, so ssh gpu-server expands to the right address, username, and key, and running nvidia-smi there confirms both the login and the GPU. VS Code then connects to that host, installs a small server on it, and opens a window where files, terminals, extensions, and notebooks all run remotely while the interface stays on your laptop. A connection that hangs usually means the SSH login itself fails, so fix plain ssh gpu-server before debugging VS Code.

Python 3.10 through 3.12 are the versions best supported by the ML ecosystem as of 2025-2026. PyTorch, TensorFlow, JAX, and most scientific libraries publish pre-built wheels for these versions, meaning pip install just works without compiling from source. Python 3.13+ introduces breaking changes to the C API that many packages haven't adapted to yet, so you'll hit installation errors with popular libraries. When in doubt, use Python 3.11 — it has the best balance of performance improvements and package compatibility.

python -m venv .venv creates a self-contained Python environment inside your project folder. When you activate it with source .venv/bin/activate, python and pip point to this local copy instead of the system Python, so installing packages for one project can't break another. The .venv folder is typically 50-200MB and should be added to .gitignore — never commit it. venv is built into Python (no extra installation), lightweight, and sufficient for most ML projects unless you need to manage multiple Python versions or non-Python binary dependencies.

Conda is both a package manager and an environment manager that handles Python versions and non-Python dependencies like CUDA, cuDNN, and MKL in a single tool. Use Miniconda (the minimal installer) rather than full Anaconda to avoid bloating your system with packages you won't use. Conda environments live in a central location (~/miniconda3/envs/) rather than inside each project, and you create them with conda create -n myenv python=3.11. The main advantage over venv is managing GPU-related libraries — conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia handles CUDA setup that would be painful with pip alone.

pip is Python's default package installer and the tool you'll use most often to add libraries to your projects. Always run pip inside an activated virtual environment — sudo pip install installs packages system-wide, which can break OS-level Python tools and create version conflicts between projects. Use pip install package==1.2.3 to pin a specific version, or pip install package>=1.2,<2.0 for a version range. Run pip install --upgrade pip periodically, as older pip versions sometimes fail to resolve complex dependency chains that newer versions handle correctly.

A requirements.txt file lists every package your project depends on with pinned version numbers, making your environment reproducible. Run pip freeze > requirements.txt to capture your current environment, and pip install -r requirements.txt to recreate it exactly. Pin exact versions (torch==2.1.0) for production and shared projects — without pinning, a teammate running pip install torch might get a different version with different behavior. For cleaner files, maintain a hand-written requirements.txt with just your direct dependencies, and use pip freeze only for full lockfiles.

This step creates the project folder and its isolated environment. apt installs the system Python along with the venv module, which Ubuntu packages separately. python3 -m venv .venv creates a .venv directory holding a link to the interpreter, a fresh pip, and an empty site-packages. source .venv/bin/activate puts .venv/bin first on your PATH, and the prompt changes to show the environment's name. The two which commands should print paths inside .venv. If they print /usr/bin, activation failed. Recent Ubuntu releases refuse pip install outside a virtual environment, because PEP 668 marks the system Python as externally managed.

With the environment active, this step installs the core stack and records exactly what was installed. Upgrading pip first avoids resolver bugs in the older copy that venv bundles. NumPy, pandas, and matplotlib handle data and plots, scikit-learn and PyTorch provide models, and JupyterLab with ipykernel adds notebooks. Registering the kernel lets Jupyter find this environment. pip freeze writes every installed package, including indirect dependencies, with an exact == version, so pip install -r requirements.txt rebuilds the same environment elsewhere. Freezing captures platform-specific CUDA builds of PyTorch, so a file frozen on a GPU Linux machine may not install on a Mac.

Two safeguards finish the environment. The .gitignore lists paths Git should never track: the virtual environment, which is large and rebuildable from requirements.txt, Python caches, datasets and model weights too big for a repository, notebook checkpoints, and editor or OS clutter. It must exist before your first git add, because files that are already committed stay tracked even after you ignore them. The smoke test imports NumPy, pandas, PyTorch, and scikit-learn and prints their versions. If any import fails, the environment is incomplete or VS Code is pointing at a different interpreter, and it is far cheaper to find that out now.

A repository is a project folder that Git tracks — it contains your code plus a hidden .git directory storing the entire change history. Create one with git init in an existing folder, or git clone URL to download a remote repo from GitHub. Every ML project should be a Git repo from day one, even personal experiments. The .git folder is what makes a directory a repo; deleting it removes all version history, so never touch it unless you know what you're doing.

A commit is a snapshot of your project at a specific point in time, tagged with a message, author, and timestamp. Good commit messages describe WHY you made the change, not just what changed — Increase batch size to 64, fixes OOM on 8GB GPU is far more useful than update config. Each commit has a unique hash (like a3b2c1d) that you can use to jump back to that exact state of your code. In ML, commits are especially valuable for reproducing results — you can always check out the exact code that produced a particular model.

A branch is an independent line of development that diverges from the main codebase. Create one with git checkout -b experiment/new-loss-function to try something risky without affecting working code. If the experiment succeeds, merge the branch back into main; if it fails, the branch stays isolated and main is untouched. In ML workflows, branches are perfect for testing different architectures, hyperparameters, or data preprocessing approaches — each experiment gets its own branch with a descriptive name.

The Git workflow has three steps: git add stages specific files (marking them for inclusion in the next commit), git commit -m 'message' saves those staged changes as a snapshot in your local repo, and git push uploads commits to a remote like GitHub. Staging exists so you can commit only the files you intend — after adding a new model and fixing a typo, you might commit them separately for a cleaner history. Use git status frequently to see which files are staged, modified, or untracked before committing.

A pull request is a GitHub feature that lets you propose merging changes from one branch into another, giving teammates a chance to review your code before it's merged. You push your branch to GitHub, open a PR through the web interface or gh pr create, and reviewers can comment on specific lines, request changes, or approve. PRs are the standard collaboration workflow in industry — even solo developers use them to maintain a clean history and document decisions. Automated checks (tests, linting) can run on every PR to catch bugs before they reach the main branch.

The one-time git config lines attach your name and email to every commit you make. git init turns the project folder into a repository by creating the hidden .git directory, and git status then lists every file as untracked. Staging named paths, rather than everything, is the discipline from Stage → Commit → Push: only source, configs, requirements, .gitignore, and the README go into the first commit. The notebooks go in a second commit with their own message, so the history explains itself. git log --oneline shows both commits, newest first. If git status lists .venv or data files, the .gitignore is missing or misspelled.

Two model architectures are tried side by side without either touching the working code on main. git checkout -b experiment/resnet50 creates a branch and switches to it. The commit made there, with the learning rate in its message, exists only on that branch. Returning to main and branching again gives the VGG16 experiment its own line of history. Switching back to main shows the edited files in their original state, because checking out a branch rewrites the working folder to match it. git merge brings the winning branch into main. Uncommitted changes follow you when you switch branches, so commit before switching.

Your history so far exists only on your laptop. This step publishes it and covers the everyday commands. git remote add origin records the GitHub repository's address under the name origin, and git push -u origin main uploads main and remembers the pairing, so later pushes need only git push. Experiment branches are pushed by name. Day to day, git pull fetches and merges teammates' work, git diff shows unstaged edits, git diff --staged shows what the next commit will contain, and git blame shows who last changed each line. git checkout -- file throws away uncommitted edits to that file, and nothing can bring them back.

If you already have VS Code, install the Jupyter extension from the Extensions sidebar (Ctrl+Shift+X, search 'Jupyter') and you're done. Create any file ending in .ipynb, and VS Code automatically opens it as a notebook with code cells, a kernel selector, and inline output. No terminal commands, no pip installs, no server management needed. VS Code even picks up your project's virtual environment as the kernel, so all your installed packages are available immediately.

Notebooks are composed of cells — small blocks that you run independently. Code cells execute Python and display output (text, tables, plots) directly below them. Markdown cells contain formatted text with headings, bold, links, and LaTeX equations for documentation. Press Shift+Enter to run the current cell and move to the next one, or Ctrl+Enter to run it and stay in place. The cell-based workflow is what makes notebooks powerful for ML: load your data once in one cell, then experiment with different transformations in subsequent cells without reloading.

The kernel is the Python process running behind your notebook — it holds all your variables, imported modules, and loaded data in memory. When you run a cell, it sends the code to the kernel for execution and displays the result. If your notebook gets into a weird state (variables you don't expect, import errors after editing modules), restart the kernel from the Kernel menu to get a clean slate. Each notebook has its own kernel, and you can choose which Python environment it uses — make sure it points to your project's virtual environment, not the system Python.

Notebooks render matplotlib, seaborn, and plotly charts directly below the code cell that generates them — no separate window, no saving to file. In modern Jupyter and VS Code, plots appear inline by default, but you can explicitly use plt.show() or the %matplotlib inline magic command if they don't. This inline visualization is what makes notebooks ideal for data exploration: plot a distribution, see it immediately, adjust parameters, rerun. For interactive plots with zoom and hover, use %matplotlib widget or plotly, which render as fully interactive HTML elements.

JupyterLab is a full-featured browser-based IDE built around notebooks, with file browsing, multiple tabs, terminals, and extensions. Install it with pip install jupyterlab and launch with jupyter lab — it opens at localhost:8888 in your browser. The key extra step is registering your virtual environment as a kernel with python -m ipykernel install --user --name myenv, otherwise JupyterLab may use the wrong Python. Most beginners should stick with VS Code's built-in Jupyter support; JupyterLab becomes useful when you want a dedicated notebook environment or need its advanced features like drag-and-drop cell rearranging.

If you set up VS Code earlier, notebooks need only one extension. code --install-extension ms-toolsai.jupyter adds notebook support, and creating any file ending in .ipynb makes VS Code open it as a notebook instead of as text. Keep notebooks in a notebooks/ folder so they stay separate from the src/ code. When you run the first cell, VS Code asks which kernel to use. Pick the interpreter inside your project's .venv, so the packages from Python Installation are available. If an import fails in the notebook but works in the terminal, the notebook is almost always attached to a different interpreter.

JupyterLab is the browser-based alternative for people who prefer a dedicated notebook interface. Install it inside the activated virtual environment so it uses that environment's packages. The critical line is python -m ipykernel install --user --name ..., which registers the environment as a named kernel. Without it, JupyterLab may start notebooks on a different Python that lacks your packages. jupyter kernelspec list shows every registered kernel and where it lives. jupyter lab starts a local server, usually on port 8888, and opens it in the browser. Closing the browser tab does not stop that server; press Ctrl+C in the terminal that started it.

Notebooks are good for exploration but awkward for production. They are hard to test, hard to import, and their mix of code and output makes Git diffs noisy. They also hide state, since cells may have run out of order. jupyter nbconvert --to script writes the notebook's code cells to a .py file, and --no-prompt drops the execution-count markers. Moving the result into src/ turns exploration into a module you can run from the terminal and review in a pull request. Always run the converted script from top to bottom once, because code that depended on a cell run out of order will fail.

A Docker image is a read-only template containing an OS, Python, installed packages, and your code — everything needed to run your application. Images are built in layers: each instruction in a Dockerfile (like RUN pip install torch) creates a new layer that gets cached. This means rebuilding after changing only your source code is fast because the pip layer is cached. Images are identified by name and tag (e.g., my-project:v1.0) and can be shared via Docker Hub or private registries so teammates get the exact same environment.

A container is a running instance of an image — think of the image as a class and the container as an object. Containers are isolated from your host system: they have their own filesystem, network, and process space, so nothing you install or break inside a container affects your laptop. You can run multiple containers from the same image simultaneously, each with different configurations. Containers are ephemeral by default — when they stop, any changes inside them are lost unless you mount volumes for persistent storage.

A Dockerfile is a text file with step-by-step instructions for building an image, starting from a base image and adding layers. Order matters for caching: put things that change rarely (system packages, pip install) near the top and things that change often (COPY source code) near the bottom. Use python:3.12-slim as your base instead of python:3.12 to cut image size from 1GB+ to ~150MB. Always include a .dockerignore file to exclude .venv/, data/, and other large directories from the build context, otherwise Docker sends gigabytes of unnecessary data.

Docker Hub is a public registry of pre-built images that saves you from installing complex software stacks from scratch. Instead of installing CUDA, cuDNN, and PyTorch manually, you pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime and everything is pre-configured and tested. Official images from NVIDIA, PyTorch, and TensorFlow are regularly updated and include GPU support out of the box. You can also push your own images to Docker Hub (or private registries like AWS ECR) to share reproducible environments with teammates or deploy to production.

Docker Compose lets you define and run multi-container applications with a single docker-compose.yml file. Instead of remembering long docker run commands with volume mounts and environment variables, you declare everything in YAML and run docker compose up. This is particularly useful for ML serving setups: define a model API container, a database container for predictions, and a monitoring container, all connected on the same network. Compose also supports GPU passthrough, environment files, and health checks, making it the standard tool for local development of multi-service architectures.

This step installs the Docker engine and proves it can run a container. The docker.io package is Ubuntu's build of the engine. On macOS and Windows you install Docker Desktop instead. The engine runs as root, so by default every command needs sudo. usermod -aG docker adds your user to the docker group, which takes effect only after you log out and back in, or run newgrp docker. docker run hello-world downloads a tiny image, starts a container that prints a message, and exits. docker ps lists running containers and docker ps -a includes stopped ones. A permission-denied error on the socket means the group change has not applied.

The Dockerfile encodes the caching rule from the Dockerfile concept. It starts from python:3.12-slim, a small official base image, and sets /app as the working directory. System packages are installed first, then requirements.txt is copied alone and installed. Because Docker reuses a cached layer until its inputs change, editing your source code rebuilds only the final layers, and the slow pip install is skipped. PYTHONUNBUFFERED makes print output appear immediately in container logs. CMD sets the default command. Copying all the source before installing requirements would invalidate the pip layer on every code change and make each rebuild take minutes.

docker build -t image-classifier:latest . builds the image from the Dockerfile in the current folder and tags it with a name, and docker images shows its size. docker run starts a container from it. Adding -it with a shell gives an interactive session inside, and --rm deletes the container when it exits. The -v flag mounts a host folder into the container, so data is read from your disk and results survive after the container is gone. Without a mount, files written inside disappear with the container. --gpus all needs NVIDIA's container toolkit. The Compose file stores these options in YAML, so docker compose up replaces a long command.

The Claude extension adds an AI panel to VS Code where you can chat about your code, ask for explanations, and request edits without leaving the editor. It reads the files you have open, so a question like "why is this loss not decreasing?" gets an answer grounded in your actual code rather than a generic one. Installation takes seconds: open Extensions (Ctrl+Shift+X), search for Claude, install Anthropic's extension, and sign in. Using it requires a paid Claude plan or API credits. Proposed edits appear as diffs you accept or reject, which keeps you in control of every change.

Copilot integrates directly into your editor and predicts what you will type next, showing grey ghost-text suggestions that you accept with Tab. It excels at boilerplate: write a function signature and docstring, and Copilot proposes the body. GitHub offers a limited free tier and paid plans, and verified students can get the paid plan free through GitHub Education. Copilot works best when your code has clear names, comments, and type hints, because the more context it sees about your intent, the better its guesses. Press Ctrl+] to cycle through alternative suggestions. Suggestions are predictions, so they can call functions that do not exist in your installed library version.

Claude Code is a terminal-based AI agent that reads your entire project, makes multi-file edits, runs commands, and iterates on errors autonomously. Install with npm install -g @anthropic-ai/claude-code and launch with claude in any project directory. Unlike extension-based tools that only see your current file, Claude Code understands your full codebase — it can refactor data pipelines across dozens of files, write and run tests, and debug complex issues. It requires an Anthropic API key with pay-per-use billing, making it best suited for developers who want maximum productivity on real projects.

Always read and understand AI-generated code before accepting it — blindly pasting suggestions leads to bugs that are harder to debug because you didn't write the code yourself. Use AI tools for boilerplate, test generation, documentation, and repetitive refactoring where correctness is easy to verify. Write critical logic yourself, especially model architectures, loss functions, and data preprocessing, since these are where subtle bugs have the biggest impact on results. Treat AI suggestions as a starting draft, not a final answer — they occasionally hallucinate API parameters, use deprecated functions, or introduce subtle logic errors.

AI assistants are remarkably effective as learning tools — ask Claude to explain a concept step by step, walk through an algorithm with a concrete example, or compare two approaches with pros and cons. When you encounter an error, paste the full traceback and ask for an explanation rather than just a fix — understanding why the error happened builds lasting knowledge. You can ask it to generate progressively harder exercises on any topic, quiz you on concepts, or review your code and suggest improvements. The key habit is to always ask "why" after getting an answer, not just "what" — this turns AI from a crutch into an accelerator for genuine understanding.

This is the lowest-friction way to add an assistant. code --install-extension anthropic.claude-code installs Anthropic's extension, or you can search for Claude in the Extensions sidebar. After signing in with your Anthropic account, which needs a paid Claude plan or API credits for Claude Code, a sidebar panel opens where you can ask about the file you are editing. You can select code and ask for an explanation, a docstring, or a fix. The assistant proposes edits that you review as a diff before accepting. Treat answers as drafts, and check anything that involves an exact API against the library's documentation.

This step adds Copilot's inline completions next to the chat-based Claude extension. The two extension IDs install the completion engine and Copilot Chat, and you sign in with your GitHub account to activate them. After that, typing a function signature and a docstring is often enough for Copilot to propose the whole body in grey text. The shortcuts in the listing accept, dismiss, and cycle through suggestions. Accepting a suggestion is not the same as checking it. Read it, run it, and keep the docstring precise, because vague comments produce plausible but wrong code. Copilot has a limited free tier, and GitHub Education grants students the paid plan.

For power users. Claude Code runs in your terminal with full project access — it can read your entire codebase, make multi-file edits, and run commands. Requires a paid Anthropic API key.

Claude Code CLI is the most powerful option — it sees your entire project and can make complex, multi-file changes. Start with the VS Code extension to learn the basics, then graduate to the CLI when you need more power.