1.3  Development Environments

1.3.1 Introducing Development Environments

Development environments are isolated setups that contain all the software, libraries, and tools needed to run code for a specific project. They ensure that code runs consistently across different machines by managing dependencies and versions.

Our stack balances ease of use, reproducibility, and professional-grade tooling. This section guides you through setting up our official development stack.

Our stack prioritizes:

• Minimal installation friction on Windows and macOS
• Small footprint suitable for roaming classroom accounts
• Reproducible environments that work identically across machines
• Free, professional tooling for students
• Strong support for AI-assisted development via VS Code + GitHub Copilot

1.3.2 Setting Up Your Development Environment

1.3.2.1 Stack Overview

The course uses a modern, streamlined development stack:

Editor & AI-Assisted Workflow

• VS Code — the primary code editor
• GitHub Copilot VS Code Extension — AI pair programming assistant (free for students via GitHub Education)

Python & Dependency Management

• uv (by Astral) — a single, fast tool that handles:
  • Installing and managing Python versions
  • Creating per-project virtual environments
  • Resolving and locking dependencies
  • Reproducible installs from committed lockfiles

Machine Learning Engine

• PyTorch — the primary deep learning framework
• CPU-first installs for reliability (GPU support is optional)

1.3.2.2 Installation Overview

Setting up your environment is a two-phase process:

1. Phase 1 (One-Time): Install VS Code and uv on your machine
2. Phase 2 (Per Repository): Bootstrap the project environment

You only do Phase 1 once per computer. Phase 2 is repeated for each project repository you clone.

1.3.2.3 Phase 1: One-Time Software Installation

Installing VS Code

VS Code is the official editor for this course. Download and install it from the official website:

1. Visit https://code.visualstudio.com/
2. Click the download button for your operating system
3. Run the installer and follow the prompts
4. Accept all default settings

After installation, launch VS Code to verify it works.

Installing VS Code Extensions:

With VS Code open, install the required extensions:

1. Click the Extensions icon in the left sidebar (or press Ctrl+Shift+X on Windows, Cmd+Shift+X on macOS)
2. Search for and install each of these extensions:
   • "Python" by Microsoft
   • "GitHub Copilot" by GitHub

These extensions only need to be installed once and will be available for all projects.

Installing uv

uv must be installed before you can set up any course projects. Choose the instructions for your operating system:

powershell -ExecutionPolicy ByPass -NoProfile -Command "irm https://astral.sh/uv/install.ps1 | iex"

uv --version

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

uv --version

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

uv --version

Installing Git

Git is required to clone and manage your project repository. Choose the instructions for your operating system:

git --version

git --version

sudo apt update
sudo apt install git

git --version

1.3.2.4 Phase 2: Bootstrapping Your Repository

Repeat this for each new project, assignment, or class. Create your project repository from the template at github.com/ricopicone/eai-project-template (Use this template → Create a new repository), then clone your new repository locally. The repo includes bootstrap scripts that automate the entire setup process.

git clone YOUR_REPO_URL
cd YOUR_REPO_NAME

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-windows.ps1

git clone YOUR_REPO_URL
cd YOUR_REPO_NAME

bash scripts/bootstrap-macos.sh

git clone YOUR_REPO_URL
cd YOUR_REPO_NAME

bash scripts/bootstrap-linux.sh

Post Installation

The bootstrap script will:

1. Check that uv is installed (fails with instructions if not)
2. Install Python 3.13 using uv
3. Create a virtual environment in .venv
4. Install all course dependencies from the lockfile (uv.lock)
5. Configure VS Code settings to use the virtual environment automatically

Once the script completes, open the project in VS Code:

1. Open VS Code
2. Select File → Open Folder...
3. Choose the folder you just cloned

The bootstrap script automatically creates VS Code workspace settings that point to the virtual environment. When you open the repository in VS Code (using code . as shown above), it should automatically detect and use the correct Python interpreter.

python --version    # Should show Python 3.13.x
python -c "import torch; print(torch.__version__)"  # Should print PyTorch version

python scripts/test-pytorch.py

1.3.2.5 Running Your First Program

Once setup is verified, try running the hello world example to confirm everything works:

python src/hello.py

You should see output displaying your PyTorch version and confirmation that your environment is ready.

This is your starting point! You can now:

1. Edit src/hello.py to experiment with Python and PyTorch
2. Create new Python files in src/ for your projects
3. Modify pyproject.toml to add additional dependencies as needed
4. Start your assignment work

1.3.2.6 Understanding the Environment Files

Your project repository contains several key files that define the Python environment:

• pyproject.toml — Declares project metadata and dependencies
• uv.lock — Locks exact versions of all packages for reproducibility (committed to git)
• .python-version — Specifies the Python version (optional, used by uv)
• .venv/ — The virtual environment directory (NOT committed to git, created locally)

The workflow ensures that all students have identical package versions, eliminating "works on my machine" issues.

1.3.2.7 Troubleshooting Common Issues

uv: command not found after installation

• Open a new terminal window — the installer modifies your PATH, which only applies to new sessions
• If still not found, manually check that uv is in your PATH (consult the uv documentation for advanced PATH troubleshooting)

VS Code doesn't show the virtual environment interpreter

• Ensure you opened the repository folder in VS Code, not a parent directory
• Try restarting VS Code
• Manually specify the interpreter path using "Python: Select Interpreter"

Git Bash terminal isn't available on Windows

• The default VS Code terminal profile is set to Git Bash (from Git for Windows)
• If it doesn't appear, open Terminal → New Terminal and choose PowerShell from the profile menu

Import errors when running Python code

• Verify the correct interpreter is selected (check the bottom-left corner of VS Code)
• Ensure the virtual environment is activated in the terminal (you should see (.venv) in the prompt)
• Run uv sync to ensure all dependencies are installed

Bootstrap script fails with "Python 3.13 not found"

• The script should automatically install Python 3.13 via uv
• If it fails, manually run uv python install 3.13 then retry the bootstrap script

Packages are missing or have wrong versions

• Run uv sync to synchronize your environment with the lockfile
• If problems persist, reset your environment by deleting .venv/ and re-running the bootstrap script

.venv\\Scripts\\Activate.ps1 cannot be loaded because running scripts is disabled on this system

• This appears in PowerShell when VS Code auto-activates the virtual environment after you run Ctrl+Shift+P → "Python: Select Interpreter".

• Open a Windows PowerShell terminal

• Run

  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

• Close and open a new PowerShell terminal. You should see (eai-project) in the terminal prompt indicating the virtual environment is active.