A repeatable notebook pattern for explaining, running, and sharing experiments.

Jupyter notebook workflow

Status: Starter guide.

Every TechClub notebook will use this pattern:

  1. Title and question — What are we trying to learn?
  2. Objectives and prerequisites
  3. Concept notes — Explain the idea before the code.
  4. Setup cell — Imports and reproducible configuration.
  5. Small example — One concept, one visible result.
  6. Experiment — Change one variable and observe.
  7. Interpretation — Explain what the output means.
  8. Practice — Complete a partially written example.
  9. Reflection — Record limitations and next questions.
  10. References — Link to primary documentation.

Notebook lessons will be runnable locally and, where possible, in a browser-based environment.

Setup

Install Jupyter in a project-specific environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip jupyter
jupyter lab

Use notebooks from the VS Code plugin

You can work in the VS Code editor with the Microsoft Python and Jupyter extensions:

  1. Install VS Code.
  2. Install the Python extension (ms-python.python) and Jupyter extension (ms-toolsai.jupyter) from the Extensions view.
  3. Open the project folder, not only the notebook file.
  4. Use Python: Select Interpreter from the Command Palette and choose .venv.
  5. Open or create an .ipynb file.
  6. Use the notebook’s Select Kernel menu to choose that same .venv interpreter.
  7. Run the setup cell first, then run cells in order with Shift+Enter.

Check the kernel before installing or importing packages:

import sys
print(sys.executable)

The path should point into the project’s .venv. Installing a package in one Python environment does not make it available in a different notebook kernel.

VS Code notebook controls

  • Run cell: Shift+Enter or the play button beside a cell.
  • Run all: use only after reviewing the notebook.
  • Restart kernel: use when cells have been run out of order or variables are stale.
  • Select kernel: use the top-right kernel picker whenever the interpreter changes.
  • Variables: inspect values while learning or debugging.
  • Python scripts: use # %% markers to create runnable cells in a .py file.

The VS Code extension is an editor interface; the notebook still runs in a Python environment. Keep the environment active when installing packages and keep the kernel selection consistent.

On Windows PowerShell, activate the environment with:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip jupyter
jupyter lab

First experiment

Create a code cell and run:

name = "Ada"
favorite_number = 7

print(f"Hello, {name}!")
print(f"Twice your number is {favorite_number * 2}.")

Then change one value, run the cell again, and describe exactly what changed. A notebook is an experiment log: keep the explanation next to the code that produced the result.

Notebook quality checklist

  • Restart the kernel and run all cells from top to bottom.
  • Keep setup and imports near the beginning.
  • Give variables descriptive names.
  • Show units for measurements.
  • Label charts and explain patterns.
  • Record assumptions and surprising results.
  • Avoid putting passwords, private data, or API keys in a notebook.

Common failure modes

  • Out-of-order cells: restart the kernel and run all cells from the top.
  • Hidden state: clear stale variables and restart before sharing.
  • Unclear output: print labels, units, and the input used for a result.
  • Non-reproducible randomness: set and record a seed for teaching experiments.
  • Uninstallable dependencies: record the Python version and package versions.
  • VS Code cannot find a kernel: select the .venv interpreter, install ipykernel in that environment, reload VS Code, and select the kernel again.
  • Imports work in the terminal but not the notebook: compare sys.executable in both places; they are probably different environments.
  • Notebook opens as raw JSON: install or enable the Microsoft Jupyter extension and reopen the .ipynb file.

Responsible notebook practice

Treat a notebook as both code and a publication. Review rendered Markdown, remove private outputs, explain surprising results, and check that downloads and links work for a new student. Use the learning and project practices checklist before sharing.

See the official Jupyter documentation for notebook and JupyterLab concepts.