Virtual Environments, Jupyter, and VS Code

1Choose Your Platform Core

This used to be three separate pages, one per operating system. It is one page now because the underlying workflow barely forks: macOS and Linux run identical commands for every step, and Windows only diverges at creating and activating the environment (section 2, step 1) and at one interpreter-path detail during verification (section 2, step 4). There is nothing to pick here beyond reading straight through -- the fork happens exactly once, right where it matters.

2The Shared Workflow Core

Four steps, run once per project: create and activate a local environment, install dependencies, register a Jupyter kernel, then point VS Code at both.

1. Create and activate your environment

   Run this from the project folder you intend to configure. This is the one step where the actual command differs by platform -- use the line that matches your shell.

   Create and activate .venv

   # Windows (PowerShell)
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   
   # Windows (Command Prompt)
   python -m venv .venv
   .venv\Scripts\activate.bat
   
   # macOS and Linux (identical)
   python3 -m venv .venv
   source .venv/bin/activate

   • Your shell prompt should show (.venv) once activation succeeds.
   • If PowerShell refuses to run the activation script, see section 4.

2. Install dependencies

   Install into the activated environment, not a global interpreter.

   Install Core dependencies

   pip install -r requirements.txt

   • Use requirements-full.txt when the course needs plotting, ML, Parquet, or web-PDF features.

3. Register the Jupyter kernel

   Install the notebook packages, then register this environment as a named kernel.

   Register a project kernel

   pip install ipykernel jupyter
   python -m ipykernel install --user --name dssl --display-name "Python (data-science-script-library)"

   Pick a project-specific --name and --display-name rather than reusing dssl across unrelated projects -- section 6 explains why that matters once a kernel list grows past one project.

4. Select the interpreter and kernel in VS Code, then verify

   The real test is whether the running notebook actually uses this environment.

   • Install the Microsoft Python and Jupyter extensions.
   • Run Python: Select Interpreter and choose .venv.
   • Open or create a notebook and select the matching kernel from the kernel picker.
   • Run import sys; print(sys.executable) in a cell and confirm the printed path includes .venv.

   The one platform difference: on Windows the printed path ends in .venv\Scripts\python.exe; on macOS and Linux it ends in .venv/bin/python. Either is correct for its platform -- what matters is that .venv appears in the path at all.

3Automation Path Core

The repository also ships a setup script that wraps the steps above into one command. It detects your operating system itself, so nothing here forks by platform.

python scripts/repo/setup/setup_student_env.py

• Its default behavior is safe: it installs the Core profile unless told otherwise.
• Swap in --deps full or --deps tensorflow-class to match the profile your course needs -- see Data Science Script Library, section 3, for the full selection rule.
• Use --interactive for prompt-driven setup instead of the non-interactive default.
• Use --dry-run to preview what the script would do without installing anything.
• Use --python to point setup at a specific interpreter -- required for the TensorFlow profile, which needs Python 3.13 exactly.
• Use --tensorflow-package to override the installed TensorFlow package name (default tensorflow) when a course requires a variant.

4Platform-Specific Troubleshooting Intermediate

The workflow above works cleanly most of the time. These are the specific, well-known points where each platform's own tooling gets in the way -- with the current fix, not just the symptom.

Windows: PowerShell blocks the activation script

Symptom: Activate.ps1 cannot be loaded because running scripts is disabled on this system. PowerShell's default execution policy blocks unsigned local scripts, and the venv activation script is one of them -- the Command Prompt .bat activation line is unaffected, so switching to it also works as a quick workaround.

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

This reverts automatically when the window closes. To fix it for your account going forward instead, use Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -- this is a persistent change to a Windows security setting, so prefer the session-only version unless you're on a machine only you use.

Separately: if python is not recognized at all, try the Windows launcher instead (py -m venv .venv), or re-run the Python installer with "Add python.exe to PATH" checked.

macOS: VS Code selects the system Python instead of .venv

Symptom: the interpreter picker shows an OS-provided Python even after you select .venv, or sys.executable doesn't include .venv after "selecting" it. Known cause: VS Code's file browser can follow .venv's interpreter symlink back to the Python that created it (system or Homebrew), silently selecting the wrong path.

• Run Python: Select Interpreter → Enter interpreter path... and type .venv/bin/python directly, instead of browsing to it.
• Prefer installing Python through Homebrew rather than using the OS-bundled interpreter -- the Python extension itself warns against using the system-managed one.

Linux: environment creation or package installation fails

Two distinct failures, both distribution-specific rather than project-specific:

• Creating .venv fails with ensurepip is not available. Recent Debian- and Ubuntu-family releases ship the venv module without its bundled pip installer as a separate package. Install it, then retry: sudo apt install python3-venv (or a version-specific package such as python3.12-venv if that name doesn't match).
• Installing packages fails with error: externally-managed-environment. Many current distributions mark the system Python as externally managed (PEP 668) so pip won't touch OS-managed packages -- this only affects the system interpreter. Installing inside an activated .venv, which this guide's workflow already does, is unaffected. Seeing this error usually means activation didn't actually happen -- confirm the prompt shows (.venv) and retry, rather than adding --break-system-packages to install into the system Python.

5Diagnosing Environment and Kernel Drift Intermediate

"Drift" is when a registered kernel and the environment it was supposed to point at stop matching -- most often after a project folder is renamed or moved, or after .venv is deleted and recreated. Symptoms: the kernel appears in VS Code's picker but fails to start, or it starts but sys.executable prints a path that no longer exists.

1. List what's actually registered

   Every kernel Jupyter knows about, and the folder its kernel spec points at:

   List registered kernels

   jupyter kernelspec list

2. Compare against the environment you expect to be using

   If the listed path doesn't match your project's current .venv location -- because the project moved, or the environment was deleted and recreated -- that mismatch is the drift, not a broken installation.

3. Re-register rather than repair

   Re-running section 2's registration step overwrites the existing kernel spec with the current, correct path -- it's idempotent, so there's no need to manually edit or repair the old one.

6Kernel Registration Internals and Cleanup Optional advanced

python -m ipykernel install --user --name ... --display-name ... (section 2, step 3) doesn't modify .venv itself. It writes a small kernel spec -- a kernel.json file plus the display name -- into a per-user Jupyter kernels directory that's entirely separate from the project folder. VS Code and Jupyter read that directory to populate the kernel picker; they don't scan disk for .venv folders directly. This is exactly why deleting a .venv doesn't remove its kernel entry on its own -- the two are linked only by the path stored inside that one file, which is also what makes section 5's drift possible in the first place.

Cleaning up a stale kernel uses the same listing command as section 5, plus one more:

jupyter kernelspec list
jupyter kernelspec uninstall <name>

Re-running the install command in section 2 overwrites any existing kernel spec with the same --name, so re-registering after moving a project is usually simpler than uninstalling first. Uninstall is for kernels you no longer want listed at all -- for example, after a project itself is finished and its .venv is gone for good. Using a distinct, project-specific --name/ --display-name pair per project (section 2, step 3) is what keeps this list legible instead of accumulating ambiguous entries that all say the same generic name.

References

1. [1] Polymath Global. VENV_AND_JUPYTER_VSCODE_TUTORIAL.md. Shared workflow model. Snapshot verified 2026-07-24.
2. [2] Polymath Global. VENV_JUPYTER_WINDOWS.md. Windows create, activate, install, and verify commands. Snapshot verified 2026-07-24.
3. [3] Polymath Global. VENV_JUPYTER_MACOS.md. macOS create, activate, install, and verify commands. Snapshot verified 2026-07-24.
4. [4] Polymath Global. VENV_JUPYTER_LINUX.md. Linux create, activate, install, and verify commands. Snapshot verified 2026-07-24.
5. [5] Polymath Global. scripts/repo/setup/setup_student_env.py. Automation script flags. Snapshot verified 2026-08-15 (Data Science Script Library lane).
6. [6] Microsoft. about_Execution_Policies. PowerShell execution policy scopes and values. Verified 2026-08-16.
7. [7] Python Software Foundation. PEP 668 -- Marking Python base environments as "externally managed". The externally-managed-environment restriction and its intended use with virtual environments. Verified 2026-08-16.
8. [8] Microsoft. Python environments in VS Code. Interpreter selection and detection behavior. Verified 2026-08-16.
9. [9] IPython/Jupyter. Installing the IPython kernel. Kernel spec registration and the meaning of --user, --name, and --display-name. Verified 2026-08-16.