Run Python and Jupyter on Your Own Computer
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 --verboseIf 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 UbuntuRestart 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 --helpIf 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-pipDo 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.txtThe prompt normally begins with (.venv) after activation. Verify that Python and pip come from the project:
which python
python -m pip --versionBoth 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-browserJupyter 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:
deactivateA6. Start it again later
cd ~/tej-computational-engineering
source .venv/bin/activate
python -m jupyter lab --no-browserIf 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.1URL if the printedlocalhostURL 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 --helpInstall 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.txtPython’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 labThe 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 labRoute C: Linux
C1. Check Python support
python3 --version
python3 -m venv --helpUse 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-pipC2. 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 labStop 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 labUsing 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.
- Sign in with an approved Google account.
- Choose File > Upload notebook and upload the required
.ipynbfile from the complete notebook bundle. - Upload any required CSV or other data file into the Colab session.
- Run the notebook from the top and download the finished
.ipynbbefore 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:
- operating system and route used;
- output of the version-check cell;
- the Python executable path;
- the command used to start Jupyter;
- a successful restart-and-run-all result;
- 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.