Run Python and Jupyter on Your Own Computer

Python
JupyterLab
WSL
Google Colab
virtual environments
local setup
Choose a Jupyter route for Windows with WSL, macOS, Linux, native Windows, or Google Colab.

Choose your route

Use the route that matches the computer you control. The links jump directly to the complete instructions.

Route When to use it
Windows with WSL Recommended for Windows. Python runs in Linux while the notebook opens in your normal Windows browser.
macOS Use Terminal and a project-specific Python virtual environment.
Linux Use the distribution’s Python packages and a project-specific virtual environment.
Native Windows PowerShell Works when WSL is unavailable, but it is not the recommended course route.
Google Colab Requires no local installation, but provides less control over files, packages, hardware, and runtime availability.

Learning goals

  • I can explain the difference between the Jupyter server, browser interface, and Python kernel.
  • I can create a project-specific virtual environment and install packages into it.
  • I can run Jupyter in WSL and open it safely in a normal Windows browser.
  • I can start, stop, reactivate, and diagnose a local Jupyter environment on macOS or Linux.

Why run Jupyter locally?

JupyterLite is useful for starting quickly, but it runs inside browser storage and supports only the packages provided by its browser kernel. Local JupyterLab can use normal files, installed Python packages, larger datasets, hardware interfaces, and later measurement tools.

Jupyter is still viewed in a browser, but the work happens locally:

terminal starts Jupyter server → browser shows JupyterLab → selected Python kernel runs code

No public website is required after the software and course files are installed.

Before you start

Use these instructions only on a computer where you are allowed to install software. Installing WSL may require administrator approval and a restart. On a managed school computer, use the approved environment or ask the teacher.

Download and extract the complete notebook bundle, or obtain the same ZIP from the teacher. It contains the notebooks, sample CSV, and requirements-jupyter.txt.

Choose one route from the route table. Windows with WSL is the recommended Windows setup. Native Windows PowerShell works, but commands and paths differ from the Linux-based course environment. Google Colab is useful when installation is impossible, but it is a cloud service rather than a local engineering environment.

Route A: Windows with WSL

WSL is the Windows Subsystem for Linux. It provides a Linux command line and filesystem while Windows continues to supply the desktop and browser.

A1. Check or install WSL

Open PowerShell and check the installed distributions:

wsl --status
wsl --list --verbose

If WSL is not installed and this is your own computer, follow the official Microsoft WSL installation guide. The normal installation command is run from an administrator PowerShell window:

wsl --install -d Ubuntu

Restart if requested. Launch Ubuntu, wait for its first-time setup, and create the Linux username and password when prompted. This Linux password is separate from the Windows sign-in and is used when an authorized system change requires sudo.

A2. Install Python support in Ubuntu

In the Ubuntu terminal, check Python first:

python3 --version
python3 -m venv --help

If venv or pip is unavailable, install the Ubuntu packages on a computer where you have permission:

sudo apt update
sudo apt install python3 python3-venv python3-pip

Do not use sudo pip install. System packages belong to Ubuntu; course packages belong inside the virtual environment created below.

A3. Put the course folder in the Linux filesystem

Keep a Linux-run project under /home, not permanently under /mnt/c, for better performance and fewer cross-filesystem permission problems.

From Ubuntu, open your Linux home folder in Windows File Explorer:

cd ~
explorer.exe .

Extract the course ZIP and copy the tej-computational-engineering folder into that window. The result should contain:

~/tej-computational-engineering/
├── data/
├── notebooks/
├── README.txt
└── requirements-jupyter.txt

Windows can also reach the same location through a path such as:

\\wsl.localhost\Ubuntu\home\your-linux-username\tej-computational-engineering

A4. Create and activate the virtual environment

In Ubuntu:

cd ~/tej-computational-engineering
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-jupyter.txt

The prompt normally begins with (.venv) after activation. Verify that Python and pip come from the project:

which python
python -m pip --version

Both paths should point inside ~/tej-computational-engineering/.venv.

A5. Start Jupyter in WSL and use the Windows browser

Keep the Ubuntu terminal open and run:

python -m jupyter lab --no-browser

Jupyter prints one or more local URLs. Copy the complete URL containing the token, for example:

http://localhost:8888/lab?token=...

Paste that URL into Chrome, Edge, or Firefox in Windows. WSL normally forwards Linux services to localhost on Windows, so the Windows browser can display the Jupyter server running inside Ubuntu. Do not share the token or bind the class server to a public network address.

Open notebooks/03a-two-loop-to-matrix-bridge.ipynb, confirm that the selected kernel belongs to .venv, and run the working cells before completing the student scaffold.

To stop Jupyter, return to Ubuntu and press Ctrl+C. Confirm shutdown if asked. Then leave the environment with:

deactivate

A6. Start it again later

cd ~/tej-computational-engineering
source .venv/bin/activate
python -m jupyter lab --no-browser

If the Windows browser cannot connect, keep the Ubuntu terminal running and try these checks before changing firewall or network settings:

python -m jupyter server list
  • Copy the exact current URL instead of reusing an old token.
  • Try the printed 127.0.0.1 URL if the printed localhost URL does not open, or the reverse.
  • Confirm that Jupyter is still running and did not exit with an error.
  • Confirm that the URL is opened on the same Windows computer running WSL.
  • Ask before changing firewall, WSL networking, or server binding settings.

Microsoft documents that Windows applications can normally reach a service running in WSL through localhost.

Route B: macOS

B1. Check Python

python3 --version
python3 -m venv --help

Install a current Python 3 release from the official Python downloads page if it is missing. Do not modify Apple’s system Python.

B2. Create the environment

Open the terminal in the extracted tej-computational-engineering folder:

cd ~/tej-computational-engineering
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-jupyter.txt

Python’s official venv documentation explains that the environment has its own interpreter and installed packages, isolated from other projects.

B3. Run Jupyter

python -m jupyter lab

The normal browser should open automatically. If it does not, copy the complete local URL printed in the terminal and paste it into the browser.

Stop the server with Ctrl+C. Reactivate it later with:

cd ~/tej-computational-engineering
source .venv/bin/activate
python -m jupyter lab

Route C: Linux

C1. Check Python support

python3 --version
python3 -m venv --help

Use the distribution’s official packages. For Ubuntu or Debian, install the usual support only when you have permission:

sudo apt update
sudo apt install python3 python3-venv python3-pip

C2. Create the environment and run Jupyter

cd ~/tej-computational-engineering
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-jupyter.txt
python -m jupyter lab

Stop the server with Ctrl+C, then run deactivate. To start again later, return to the project folder, activate .venv, and run python -m jupyter lab.

Route D: native Windows PowerShell

Use this route if WSL is unavailable and a normal per-user Python installation is permitted. It works, but it is not the recommended course route because Windows paths, activation, and command-line behaviour differ from the WSL and Linux instructions used elsewhere in the course.

py --version
Set-Location "$HOME\tej-computational-engineering"
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements-jupyter.txt
.\.venv\Scripts\python.exe -m jupyter lab

Using the direct .venv interpreter works even when PowerShell activation scripts are blocked. Do not weaken the computer-wide execution policy for this course.

Route E: Google Colab

Open Google Colab when you cannot install Python or Jupyter locally.

  1. Sign in with an approved Google account.
  2. Choose File > Upload notebook and upload the required .ipynb file from the complete notebook bundle.
  3. Upload any required CSV or other data file into the Colab session.
  4. Run the notebook from the top and download the finished .ipynb before ending the session.

Colab is convenient because there is no local setup, but the code runs in a temporary cloud virtual machine. The runtime can disconnect or be replaced, local files are not automatically available, and free resources are neither guaranteed nor unlimited. For these small course notebooks, startup, uploads, Google Drive access, and network delay can make Colab feel slower than a prepared local environment. It also gives you less control over Python versions, installed packages, USB devices, serial ports, and measurement hardware. Use local Jupyter for repeatable engineering work whenever possible. See the official Google Colab FAQ for current runtime and resource limitations.

Verify the environment

Run this in a notebook cell:

import sys
import numpy as np
import pandas as pd
import matplotlib

print("Python executable:", sys.executable)
print("Python:", sys.version)
print("NumPy:", np.__version__)
print("pandas:", pd.__version__)
print("Matplotlib:", matplotlib.__version__)

The executable should point inside this project’s .venv. Restart the kernel and run one supplied notebook from top to bottom.

Common issues

Problem Evidence and next check
python3 or py not found Verify the selected operating-system route and reopen the terminal after installing Python.
venv creation fails on Ubuntu Confirm that python3-venv is installed for the active Ubuntu release.
ModuleNotFoundError Print sys.executable. Install the package with that environment’s python -m pip, not an unrelated pip.
Jupyter command is missing Run the .venv interpreter with python -m jupyter lab and confirm requirements-jupyter.txt installed successfully.
WSL browser cannot connect Keep Jupyter running, copy the current token URL, try localhost and 127.0.0.1, and run python -m jupyter server list.
Notebook uses the wrong kernel Choose Kernel > Change Kernel and select the Python interpreter inside .venv.
CSV file cannot be found Run from pathlib import Path; print(Path.cwd()) and place the file relative to that working directory.
Port 8888 is busy Stop the previous server or run python -m jupyter lab --port 8890. Do not open a public firewall port.
PowerShell blocks activation Use .\.venv\Scripts\python.exe directly.
Colab files disappear after reconnecting Upload the required files again and download completed work before ending the temporary runtime.
Colab package or version differs Check the runtime’s Python and package versions. Use a local .venv when the course requires a controlled environment.

Environment evidence to submit

Record:

  1. operating system and route used;
  2. output of the version-check cell;
  3. the Python executable path;
  4. the command used to start Jupyter;
  5. a successful restart-and-run-all result;
  6. one problem encountered and the evidence used to resolve it.

Do not submit passwords, Jupyter tokens, private home-directory details, or screenshots containing unrelated personal information.

Next steps

Continue to Find Documentation and Ask for Programming Help. The official Jupyter installation page documents the basic pip install jupyterlab and jupyter lab workflow; this course uses python -m pip and a virtual environment so the intended interpreter is explicit.

Help improve this lesson (optional)

If a setup step was unclear or failed, tell the teacher the step, operating system, exact error, and one change that would help the next student. If you can fix the wording, command, or screenshot, show the teacher. A useful fix may be added to the course website and credited to you.