Skip to content

VS Code Essentials

The most popular editor for Python data science: fast, free, and deeply integrated with Python, Jupyter, and Git. One tool for scripts, notebooks, debugging, and pull requests.

Table of Contents

Installation / Setup

# macOS
brew install --cask visual-studio-code
# then: code --version ; code . (open current folder)
# CLI helper on Windows/Linux: enable "Shell command: Install 'code' command" in palette

Must-have extensions (Extensions panel: Ctrl/Cmd+Shift+X):

Extension Why
Python (Microsoft) IntelliSense, debugging, envs
Jupyter (Microsoft) .ipynb editing in VS Code
Pylance type checking, autocomplete
Ruff fast linting + formatting
GitLens blame/history inline
GitHub Pull Requests review/merge PRs without leaving
Remote — SSH / WSL / Dev Containers code on servers or containers
Even Better TOML / YAML config files
Data Wrangler (optional) visual pandas exploration

Core Syntax

Keyboard shortcuts (the essentials)

Shortcut (Win / macOS) Action
Ctrl+P / Cmd+P quick open file
Ctrl+Shift+P / Cmd+Shift+P command palette
Ctrl+ ` / Cmd+ ` toggle terminal
Ctrl+Shift+E / Cmd+Shift+E file explorer
Ctrl+Shift+G / Cmd+Shift+G source control (git)
F5 start debugging
F9 toggle breakpoint
F12 go to definition
Alt+Shift+F / Opt+Shift+F format document
Shift+Enter run current cell/line (notebooks)
Ctrl+/ / Cmd+/ toggle comment
Ctrl+D / Cmd+D select next occurrence
Ctrl+Shift+K / Cmd+Shift+K delete line
Alt+↑/↓ / Opt+↑/↓ move line

Python environment selection

# Create a venv first (see python-virtual-environments.md)
python -m venv .venv && source .venv/bin/activate
  • Ctrl/Cmd+Shift+P → Python: Select Interpreter → choose .venv.
  • VS Code then uses that env for IntelliSense, debugging, and notebooks.
  • The selected interpreter shows in the bottom-right status bar — verify it!

Settings (JSON: Ctrl/Cmd+, → open settings.json)

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "editor.formatOnSave": true,
  "editor.rulers": [88],
  "python.analysis.typeCheckingMode": "basic",
  "notebook.cellToolbarLocation": "right"
}

Common Operations

Run & debug Python

# debugger is the big win: F9 breakpoint, F5 start, inspect variables
def train(model, X, y):
    pred = model.predict(X)     # breakpoint here
    ...

Create .vscode/launch.json via Run → Add Configuration, or just use F5 with the Python extension.

Jupyter notebooks in VS Code

  • Open .ipynb — full notebook UI: run cells (Shift+Enter), variable explorer, data viewer.
  • Pick the kernel from the same selected interpreter.
  • Convert between notebook and script: palette → Jupyter: Export to Python Script.

Integrated Git

  1. Ctrl+Shift+G opens Source Control.
  2. Type a commit message, click the ✓ to commit staged changes.
  3. Click the branch icon in the bottom-left to switch branches / publish.
  4. GitHub PR extension: review and merge PRs in-editor.

Terminal & profiles

# multiple terminals side by side
# default shell profile: Ctrl+Shift+P -> "Terminal: Select Default Profile"
uv run python train.py        # run within the project env

Practical Examples

1. Reproducible data-science workspace

// .vscode/settings.json committed to the repo:
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "ruff.format.args": ["--line-length", "88"]
}

Add extensions.json so teammates get prompted for the same extensions.

2. Debug a failing training loop

# launch.json (F5) — attach the debugger and inspect tensors at breakpoints
{
  "version": "0.2.0",
  "configurations": [{
    "name": "Python: train.py",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/train.py",
    "args": ["--lr", "0.001"],
    "console": "integratedTerminal"
  }]
}

3. Lint + typecheck on save

pip install ruff mypy        # or: uv add --dev ruff mypy
# settings.json:
#   "editor.formatOnSave": true,
#   "[python]": {"editor.defaultFormatter": "charliermarsh.ruff"}
#   "python.analysis.typeCheckingMode": "standard"

Common Patterns

# Multi-root workspaces for repo + notebooks
code repo.code-workspace

# Open a folder on a remote server
#   Remote-SSH: connect to host, then File > Open Folder

# Notebook + script duality: keep logic in .py modules,
# notebooks thin and executable:
#   from myproject.features import build_features

Best Practices

  • Commit .vscode/settings.json (non-private) so the team shares formatting/test config.
  • Select the interpreter once per project; put .venv in .gitignore.
  • Use the debugger, not print() — breakpoints + variable watch save hours.
  • Format with Ruff on save to keep diffs clean.
  • Leverage Pylance type-checking (basic/standard) on data pipelines.
  • Keep notebooks under version control cleanly: strip outputs (nbstripout) before commit.
  • Use tasks/terminal profiles for repeatable commands (train, test, lint).

Common Mistakes

Mistake Consequence Fix
Running the wrong interpreter ModuleNotFoundError for installed packages Bottom-right shows env; select .venv
Not saving before format-on-save Confusion about changes Auto-save or Ctrl/Cmd+S habit
Debugging a different file than F5 expects Weird behavior Set the program/entry in launch.json
Giant notebook in git Unreviewable diffs Export to script; strip outputs
Editing remote files without Remote-SSH Editing a local copy Use Remote — SSH extension
Ignoring Pylance squiggles Missed type bugs Enable basic type checking

Troubleshooting

Symptom Cause Fix
Linter says "ruff: command not found" Ruff not installed in selected env pip install ruff; reload window
Autocomplete missing Pylance/Python ext not active Install extensions; select interpreter
Notebook kernel dies Env mismatch / memory Check kernel selection; restart kernel
git panel empty Folder not a repo git init / open the repo folder
Terminal uses different Python Shell not activating venv Activate in terminal or set default profile

Official Documentation

Last Updated

2026-09-06 — Initial version.